makit 0.0.99 → 0.0.112

data/lib/makit/commands/result.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Makit
+  module Commands
+    # Structured result objects with comprehensive metadata.
+    # Uses native Ruby objects instead of protobuf for better performance.
+    #
+    # @example Basic result creation
+    #   result = Result.new(
+    #     command: "git --version",
+    #     exit_code: 0,
+    #     stdout: "git version 2.39.5\n",
+    #     stderr: ""
+    #   )
+    #
+    # @example Result with full metadata
+    #   result = Result.new(
+    #     command: "bundle install",
+    #     exit_code: 0,
+    #     stdout: "Bundle complete!",
+    #     stderr: "",
+    #     started_at: Time.now - 10,
+    #     finished_at: Time.now,
+    #     metadata: { gems_installed: 42, cache_hit: true }
+    #   )
+    class Result
+      # Command execution result with comprehensive metadata.
+      #
+      # @!attribute [r] command
+      #   @return [String] the command that was executed
+      # @!attribute [r] exit_code
+      #   @return [Integer] process exit code
+      # @!attribute [r] stdout
+      #   @return [String] standard output
+      # @!attribute [r] stderr
+      #   @return [String] standard error output
+      # @!attribute [r] started_at
+      #   @return [Time] when execution started
+      # @!attribute [r] finished_at
+      #   @return [Time, nil] when execution finished
+      # @!attribute [r] duration
+      #   @return [Float, nil] execution duration in seconds
+      # @!attribute [r] metadata
+      #   @return [Hash] additional metadata
+      attr_reader :command, :exit_code, :stdout, :stderr, :started_at, :finished_at, :duration, :metadata
+
+      # Initialize a new command result.
+      #
+      # @param command [String] the command that was executed
+      # @param exit_code [Integer] process exit code (default: nil)
+      # @param stdout [String] standard output (default: "")
+      # @param stderr [String] standard error output (default: "")
+      # @param started_at [Time] when execution started (default: Time.now)
+      # @param finished_at [Time, nil] when execution finished
+      # @param metadata [Hash] additional metadata (default: {})
+      def initialize(command:, **attributes)
+        @command = command.to_s
+        @exit_code = attributes[:exit_code]
+        @stdout = attributes[:stdout] || ""
+        @stderr = attributes[:stderr] || ""
+        @started_at = attributes[:started_at] || Time.now
+        @finished_at = attributes[:finished_at]
+        @duration = calculate_duration
+        @metadata = attributes[:metadata] || {}
+
+        # Ensure output is always strings
+        @stdout = @stdout.to_s
+        @stderr = @stderr.to_s
+      end
+
+      # Mark the result as finished.
+      #
+      # @param finished_at [Time] when execution finished (default: Time.now)
+      # @param exit_code [Integer] process exit code
+      # @param stdout [String] standard output
+      # @param stderr [String] standard error output
+      # @return [self] for method chaining
+      def finish!(finished_at: Time.now, exit_code: nil, stdout: nil, stderr: nil)
+        @finished_at = finished_at
+        @duration = calculate_duration
+        @exit_code = exit_code if exit_code
+        @stdout = stdout.to_s if stdout
+        @stderr = stderr.to_s if stderr
+        self
+      end
+
+      # Check if the command executed successfully.
+      #
+      # @return [Boolean] true if exit code is 0
+      def success?
+        exit_code.zero?
+      end
+
+      # Check if the command execution failed.
+      #
+      # @return [Boolean] true if exit code is not 0
+      def failure?
+        !success?
+      end
+
+      # Check if the command execution is complete.
+      #
+      # @return [Boolean] true if finished_at is set
+      def finished?
+        !finished_at.nil?
+      end
+
+      # Check if the command is still running.
+      #
+      # @return [Boolean] true if execution started but not finished
+      def running?
+        !started_at.nil? && finished_at.nil?
+      end
+
+      # Get combined output (stdout + stderr).
+      #
+      # @return [String] combined output
+      def output
+        [stdout, stderr].reject(&:empty?).join("\n")
+      end
+
+      # Get the first line of stdout (useful for simple commands).
+      #
+      # @return [String, nil] first line of stdout
+      def first_line
+        return nil if stdout.empty?
+
+        stdout.lines.first&.chomp
+      end
+
+      # Get the last line of stdout (useful for progress indicators).
+      #
+      # @return [String, nil] last line of stdout
+      def last_line
+        return nil if stdout.empty?
+
+        stdout.lines.last&.chomp
+      end
+
+      # Check if output contains specific text.
+      #
+      # @param text [String] text to search for
+      # @param case_sensitive [Boolean] whether to perform case-sensitive search
+      # @return [Boolean] true if text is found in stdout or stderr
+      def contains?(text, case_sensitive: true)
+        search_text = case_sensitive ? text : text.downcase
+        search_stdout = case_sensitive ? stdout : stdout.downcase
+        search_stderr = case_sensitive ? stderr : stderr.downcase
+
+        search_stdout.include?(search_text) || search_stderr.include?(search_text)
+      end
+
+      # Convert result to hash representation.
+      #
+      # @return [Hash] hash representation of the result
+      def to_h
+        {
+          command: command,
+          exit_code: exit_code,
+          stdout: stdout,
+          stderr: stderr,
+          started_at: started_at&.iso8601,
+          finished_at: finished_at&.iso8601,
+          duration: duration,
+          success: success?,
+          metadata: metadata,
+        }
+      end
+
+      # Convert result to JSON representation.
+      #
+      # @param args [Array] arguments passed to JSON.generate
+      # @return [String] JSON representation
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      # Create result from hash representation.
+      #
+      # @param hash [Hash] hash containing result information
+      # @return [Result] new result object
+      def self.from_hash(hash)
+        # Parse time strings back to Time objects
+        started_at = hash[:started_at] || hash["started_at"]
+        finished_at = hash[:finished_at] || hash["finished_at"]
+
+        started_at = Time.iso8601(started_at) if started_at.is_a?(String)
+        finished_at = Time.iso8601(finished_at) if finished_at.is_a?(String)
+
+        new(
+          command: hash[:command] || hash["command"],
+          exit_code: hash[:exit_code] || hash["exit_code"],
+          stdout: hash[:stdout] || hash["stdout"] || "",
+          stderr: hash[:stderr] || hash["stderr"] || "",
+          started_at: started_at,
+          finished_at: finished_at,
+          metadata: hash[:metadata] || hash["metadata"] || {},
+        )
+      end
+
+      # Create result from JSON string.
+      #
+      # @param json_string [String] JSON string representation
+      # @return [Result] new result object
+      # @raise [JSON::ParserError] if JSON is invalid
+      def self.from_json(json_string)
+        hash = JSON.parse(json_string)
+        from_hash(hash)
+      end
+
+      # Create a failed result with error information.
+      #
+      # @param command [String] the command that failed
+      # @param error [Exception, String] error that occurred
+      # @param started_at [Time] when execution started
+      # @return [Result] failed result object
+      def self.failure(command:, error:, started_at: Time.now)
+        error_message = error.is_a?(Exception) ? error.message : error.to_s
+        error_class = error.is_a?(Exception) ? error.class.name : "Error"
+
+        new(
+          command: command,
+          exit_code: 1,
+          stdout: "",
+          stderr: error_message,
+          started_at: started_at,
+          finished_at: Time.now,
+          metadata: { error_class: error_class, failed: true },
+        )
+      end
+
+      # Create a successful result.
+      #
+      # @param command [String] the command that succeeded
+      # @param stdout [String] standard output
+      # @param started_at [Time] when execution started
+      # @param duration [Float] execution duration
+      # @return [Result] successful result object
+      def self.success(command:, stdout: "", started_at: Time.now, duration: nil)
+        finished_at = duration ? started_at + duration : Time.now
+
+        new(
+          command: command,
+          exit_code: 0,
+          stdout: stdout,
+          stderr: "",
+          started_at: started_at,
+          finished_at: finished_at,
+        )
+      end
+
+      # Add metadata to the result.
+      #
+      # @param key [String, Symbol] metadata key
+      # @param value [Object] metadata value
+      # @return [self] for method chaining
+      def add_metadata(key, value)
+        @metadata[key] = value
+        self
+      end
+
+      # Merge additional metadata.
+      #
+      # @param additional_metadata [Hash] metadata to merge
+      # @return [self] for method chaining
+      def merge_metadata(additional_metadata)
+        @metadata.merge!(additional_metadata)
+        self
+      end
+
+      # Get execution summary for logging/display.
+      #
+      # @return [String] human-readable execution summary
+      def summary
+        status = success? ? "✓" : "✗"
+        duration_text = duration ? " (#{format("%.2f", duration)}s)" : ""
+
+        "#{status} #{command}#{duration_text}"
+      end
+
+      # Get detailed execution information.
+      #
+      # @return [String] detailed execution information
+      def details
+        lines = []
+        lines << "Command: #{command}"
+        lines << "Exit Code: #{exit_code}"
+        lines << "Started: #{started_at}"
+        lines << "Finished: #{finished_at}" if finished_at
+        lines << "Duration: #{format("%.2f", duration)}s" if duration
+        lines << "Status: #{success? ? "Success" : "Failed"}"
+
+        unless stdout.empty?
+          lines << "STDOUT:"
+          lines << stdout.split("\n").map { |line| "  #{line}" }
+        end
+
+        unless stderr.empty?
+          lines << "STDERR:"
+          lines << stderr.split("\n").map { |line| "  #{line}" }
+        end
+
+        lines << "Metadata: #{metadata}" unless metadata.empty?
+
+        lines.flatten.join("\n")
+      end
+
+      private
+
+      # Calculate execution duration.
+      #
+      # @return [Float, nil] duration in seconds, or nil if not finished
+      def calculate_duration
+        return nil unless started_at && finished_at
+
+        finished_at - started_at
+      end
+    end
+  end
+end

data/lib/makit/commands/runner.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require_relative "request"
+require_relative "result"
+require_relative "strategies/synchronous"
+require_relative "middleware/base"
+require_relative "middleware/unified_logger"
+require_relative "middleware/command_logger"
+
+module Makit
+  module Commands
+    # Modern command execution engine with proper separation of concerns.
+    #
+    # The Runner coordinates command execution through a middleware chain and
+    # execution strategies. It provides a clean, extensible architecture for
+    # command processing with support for caching, logging, validation, and
+    # custom execution patterns.
+    #
+    # @example Basic usage
+    #   runner = Runner.new
+    #   request = Request.from_string("git --version")
+    #   result = runner.execute(request)
+    #   puts result.stdout
+    #
+    # @example With custom middleware
+    #   runner = Runner.new(middleware: [Logger.new, Cache.new])
+    #   result = runner.execute(request)
+    #
+    # @example With custom strategy
+    #   runner = Runner.new(strategy: Strategies::Parallel.new)
+    #   results = runner.execute_batch(requests)
+    class Runner
+      # @!attribute [r] middleware
+      #   @return [Array<Middleware::Base>] middleware chain
+      # @!attribute [r] strategy
+      #   @return [Strategies::Base] execution strategy
+      attr_reader :middleware, :strategy
+
+      # Get the default configured runner instance.
+      #
+      # @return [Runner] default runner with standard middleware
+      def self.default
+        # Recreate the runner if the log level has changed
+        current_log_level = Makit::Logging.current_log_level
+        if @default.nil? || @last_log_level != current_log_level
+          @last_log_level = current_log_level
+          @default = new(
+            middleware: [
+              Middleware::CommandLogger.new(
+                log_stdout: true,
+                log_stderr: true,
+                log_performance: true,
+                max_output_lines: 50,
+              ),
+            ],
+          )
+        end
+        @default
+      end
+
+      # Initialize a new command runner.
+      #
+      # @param middleware [Array<Middleware::Base>] middleware chain
+      # @param strategy [Strategies::Base] execution strategy
+      # @param options [Hash] additional configuration
+      def initialize(middleware: nil, strategy: nil, **options)
+        @middleware = Array(middleware || default_middleware)
+        @strategy = strategy || Strategies::Synchronous.new
+        @options = options
+
+        validate_middleware
+        validate_strategy
+
+        # Log runner initialization
+        log_runner_initialization
+      end
+
+      # Execute a single command request.
+      #
+      # @param request [Request, String, Hash] command request to execute
+      # @return [Result] execution result
+      # @raise [ArgumentError] if request is invalid
+      def execute(request)
+        # Normalize request to Request object
+        normalized_request = normalize_request(request)
+
+        # Apply middleware chain
+        execute_with_middleware(normalized_request) do |processed_request|
+          @strategy.execute(processed_request)
+        end
+      end
+
+      # Execute multiple command requests.
+      #
+      # @param requests [Array<Request, String, Hash>] requests to execute
+      # @return [Array<Result>] execution results
+      def execute_batch(requests)
+        # Normalize all requests
+        normalized_requests = requests.map { |req| normalize_request(req) }
+
+        # Use strategy's batch execution if available, otherwise execute individually
+        if @strategy.respond_to?(:execute_batch)
+          # Apply middleware to the entire batch
+          execute_with_middleware_batch(normalized_requests) do |processed_requests|
+            @strategy.execute_batch(processed_requests)
+          end
+        else
+          # Execute each request individually with middleware
+          normalized_requests.map { |request| execute(request) }
+        end
+      end
+
+      # Add middleware to the execution chain.
+      #
+      # @param middleware_instance [Middleware::Base] middleware to add
+      # @return [self] for method chaining
+      def add_middleware(middleware_instance)
+        validate_middleware_instance(middleware_instance)
+        @middleware << middleware_instance
+        self
+      end
+
+      # Remove middleware from the execution chain.
+      #
+      # @param middleware_class [Class] middleware class to remove
+      # @return [self] for method chaining
+      def remove_middleware(middleware_class)
+        @middleware.reject! { |m| m.is_a?(middleware_class) }
+        self
+      end
+
+      # Check if specific middleware is present.
+      #
+      # @param middleware_class [Class] middleware class to check
+      # @return [Boolean] true if middleware is present
+      def has_middleware?(middleware_class)
+        @middleware.any? { |m| m.is_a?(middleware_class) }
+      end
+
+      # Get runner configuration for debugging.
+      #
+      # @return [Hash] runner configuration
+      def config
+        {
+          middleware: @middleware.map(&:config),
+          strategy: @strategy.config,
+          options: @options,
+        }
+      end
+
+      # Get execution statistics.
+      #
+      # @return [Hash] execution statistics
+      def stats
+        @stats ||= {
+          total_executions: 0,
+          successful_executions: 0,
+          failed_executions: 0,
+          total_duration: 0.0,
+        }
+      end
+
+      private
+
+      # Execute request with middleware chain.
+      #
+      # @param request [Request] normalized request
+      # @yield [Request] yields processed request to execution
+      # @return [Result] execution result
+      def execute_with_middleware(request, &block)
+        # Build middleware chain
+        chain = build_middleware_chain(request)
+
+        # Execute chain
+        result = chain.call(request, &block)
+
+        # Log high-level success/error using the default logger
+        log_command_result(request, result)
+
+        # Update statistics
+        update_stats(result)
+
+        result
+      end
+
+      # Execute batch with middleware chain.
+      #
+      # @param requests [Array<Request>] normalized requests
+      # @yield [Array<Request>] yields processed requests to execution
+      # @return [Array<Result>] execution results
+      def execute_with_middleware_batch(requests, &block)
+        # For batch execution, apply middleware to each request individually
+        # This maintains the middleware contract while supporting batch execution
+        results = requests.map do |request|
+          execute_with_middleware(request) { |req| [req] }
+        end.flatten
+
+        # Then execute the batch
+        processed_requests = results.map(&:command).map { |cmd| Request.from_string(cmd) }
+        batch_results = block.call(processed_requests)
+
+        # Update statistics for batch
+        batch_results.each { |result| update_stats(result) }
+
+        batch_results
+      end
+
+      # Build middleware execution chain.
+      #
+      # @param request [Request] the request to process
+      # @return [Proc] middleware chain
+      def build_middleware_chain(request)
+        # Filter middleware that applies to this request
+        applicable_middleware = @middleware.select { |m| m.applicable?(request) }
+
+        # Build chain in reverse order so first middleware wraps everything
+        applicable_middleware.reverse.reduce(method(:execute_final)) do |chain, middleware|
+          ->(req) { middleware.call(req, &chain) }
+        end
+      end
+
+      # Final execution step (after all middleware).
+      #
+      # @param request [Request] processed request
+      # @return [Result] execution result
+      def execute_final(request)
+        @strategy.execute(request)
+      end
+
+      # Normalize various input types to Request objects.
+      #
+      # @param request [Request, String, Hash] request in various formats
+      # @return [Request] normalized request
+      # @raise [ArgumentError] if request cannot be normalized
+      def normalize_request(request)
+        case request
+        when Request
+          request
+        when String
+          Request.from_string(request)
+        when Hash
+          Request.from_hash(request)
+        else
+          raise ArgumentError, "Invalid request type: #{request.class}. Expected Request, String, or Hash."
+        end
+      end
+
+      # Update execution statistics.
+      #
+      # @param result [Result] execution result
+      def update_stats(result)
+        stats[:total_executions] += 1
+
+        if result.success?
+          stats[:successful_executions] += 1
+        else
+          stats[:failed_executions] += 1
+        end
+
+        stats[:total_duration] += result.duration if result.duration
+      end
+
+      # Get default middleware chain.
+      #
+      # @return [Array<Middleware::Base>] default middleware
+      def default_middleware
+        # No default middleware for now - keep it simple
+        # Subclasses or configuration can add middleware as needed
+        []
+      end
+
+      # Validate middleware array.
+      def validate_middleware
+        @middleware.each { |m| validate_middleware_instance(m) }
+      end
+
+      # Validate individual middleware instance.
+      #
+      # @param middleware [Object] middleware to validate
+      # @raise [ArgumentError] if middleware is invalid
+      def validate_middleware_instance(middleware)
+        unless middleware.respond_to?(:call)
+          raise ArgumentError, "Middleware must respond to #call: #{middleware.class}"
+        end
+
+        return if middleware.respond_to?(:applicable?)
+
+        raise ArgumentError, "Middleware must respond to #applicable?: #{middleware.class}"
+      end
+
+      # Validate execution strategy.
+      #
+      # @raise [ArgumentError] if strategy is invalid
+      def validate_strategy
+        unless @strategy.respond_to?(:execute)
+          raise ArgumentError, "Strategy must respond to #execute: #{@strategy.class}"
+        end
+
+        return if @strategy.respond_to?(:supports?)
+
+        raise ArgumentError, "Strategy must respond to #supports?: #{@strategy.class}"
+      end
+
+      # Log command execution result using the default logger.
+      #
+      # @param request [Request] the executed request
+      # @param result [Result] the execution result
+      # @return [void]
+      def log_command_result(request, result)
+        # Build the full command string
+        command_string = "#{request.command} #{request.arguments&.join(' ')}".strip
+
+        # Log success or error using the default logger
+        if result.success?
+          Makit::Logging.success(command_string)
+        else
+          Makit::Logging.error(command_string)
+        end
+      end
+
+      # Log runner initialization for debugging.
+      #
+      # @return [void]
+      def log_runner_initialization
+        # Only log if we have a unified logger middleware
+        logger_middleware = @middleware.find { |m| m.is_a?(Middleware::UnifiedLogger) }
+        return unless logger_middleware
+
+        logger_middleware.logger.debug("Command runner initialized",
+                                       middleware_count: @middleware.length,
+                                       strategy: @strategy.class.name,
+                                       working_directory: Dir.pwd,
+                                       options: @options)
+      end
+    end
+  end
+end