aidp 0.34.0 → 0.39.3

data/lib/aidp/interfaces/binary_checker_interface.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Interfaces
+    # BinaryCheckerInterface defines the contract for checking CLI binary availability.
+    # This interface allows for dependency injection of different binary checking
+    # implementations, facilitating extraction of provider code into standalone gems.
+    #
+    # @example Implementing the interface
+    #   class MyBinaryChecker
+    #     include Aidp::Interfaces::BinaryCheckerInterface
+    #
+    #     def available?(binary_name)
+    #       system("which", binary_name, out: File::NULL, err: File::NULL)
+    #     end
+    #
+    #     def path_for(binary_name)
+    #       `which #{binary_name}`.chomp
+    #     end
+    #   end
+    #
+    # @example Using an injected checker
+    #   class Provider
+    #     def initialize(binary_checker: PathBinaryChecker.new)
+    #       @binary_checker = binary_checker
+    #     end
+    #
+    #     def available?
+    #       @binary_checker.available?("claude")
+    #     end
+    #   end
+    #
+    module BinaryCheckerInterface
+      # Check if a binary is available in the system PATH.
+      #
+      # @param binary_name [String] the name of the binary to check (e.g., "claude", "cursor-agent")
+      # @return [Boolean] true if the binary is executable and in PATH
+      def available?(binary_name)
+        raise NotImplementedError, "#{self.class} must implement #available?"
+      end
+
+      # Get the full path to a binary.
+      #
+      # @param binary_name [String] the name of the binary to find
+      # @return [String, nil] the full path to the binary, or nil if not found
+      def path_for(binary_name)
+        raise NotImplementedError, "#{self.class} must implement #path_for"
+      end
+    end
+
+    # NullBinaryChecker always returns false/nil.
+    # Useful for testing when no binaries should be considered available.
+    #
+    # @example Using in tests
+    #   provider = Provider.new(binary_checker: NullBinaryChecker.new)
+    #   provider.available? # => false
+    #
+    class NullBinaryChecker
+      include BinaryCheckerInterface
+
+      def available?(binary_name)
+        false
+      end
+
+      def path_for(binary_name)
+        nil
+      end
+    end
+
+    # StubBinaryChecker returns configurable responses.
+    # Useful for testing specific scenarios.
+    #
+    # @example Stubbing availability
+    #   checker = StubBinaryChecker.new(available: {"claude" => true, "cursor-agent" => false})
+    #   checker.available?("claude")       # => true
+    #   checker.available?("cursor-agent") # => false
+    #   checker.available?("unknown")      # => false
+    #
+    class StubBinaryChecker
+      include BinaryCheckerInterface
+
+      # @param available [Hash<String, Boolean>] map of binary names to availability
+      # @param paths [Hash<String, String>] map of binary names to paths
+      def initialize(available: {}, paths: {})
+        @available = available
+        @paths = paths
+      end
+
+      def available?(binary_name)
+        @available.fetch(binary_name.to_s, false)
+      end
+
+      def path_for(binary_name)
+        @paths[binary_name.to_s]
+      end
+    end
+
+    # PathBinaryChecker checks the system PATH for binaries.
+    # This is the standard implementation used by AIDP.
+    #
+    # @example Creating a checker
+    #   checker = PathBinaryChecker.new
+    #   checker.available?("ruby") # => true
+    #   checker.path_for("ruby")   # => "/usr/bin/ruby"
+    #
+    class PathBinaryChecker
+      include BinaryCheckerInterface
+
+      # Check if a binary is available in the system PATH.
+      #
+      # @param binary_name [String] the name of the binary to check
+      # @return [Boolean] true if the binary is executable and in PATH
+      def available?(binary_name)
+        !path_for(binary_name).nil?
+      end
+
+      # Get the full path to a binary.
+      # Searches the PATH environment variable for the binary.
+      #
+      # @param binary_name [String] the name of the binary to find
+      # @return [String, nil] the full path to the binary, or nil if not found
+      def path_for(binary_name)
+        return nil if binary_name.nil? || binary_name.empty?
+
+        # Get extensions to check (Windows support)
+        extensions = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+
+        # Search each PATH directory
+        ENV["PATH"].to_s.split(File::PATH_SEPARATOR).each do |dir|
+          extensions.each do |ext|
+            path = File.join(dir, "#{binary_name}#{ext}")
+            return path if File.executable?(path) && !File.directory?(path)
+          end
+        end
+
+        nil
+      end
+    end
+
+    # CachingBinaryChecker wraps another checker with TTL-based caching.
+    # Reduces filesystem checks for frequently-queried binaries.
+    #
+    # @example Creating a caching checker
+    #   inner_checker = PathBinaryChecker.new
+    #   checker = CachingBinaryChecker.new(inner_checker, ttl: 60)
+    #   checker.available?("ruby") # filesystem check
+    #   checker.available?("ruby") # cached result
+    #
+    class CachingBinaryChecker
+      include BinaryCheckerInterface
+
+      # Default cache TTL in seconds (5 minutes)
+      DEFAULT_TTL = 300
+
+      # @param checker [BinaryCheckerInterface] the underlying checker to cache
+      # @param ttl [Integer] cache time-to-live in seconds
+      def initialize(checker, ttl: DEFAULT_TTL)
+        @checker = checker
+        @ttl = ttl
+        @cache = {}
+        @path_cache = {}
+      end
+
+      def available?(binary_name)
+        key = binary_name.to_s
+        cached = @cache[key]
+
+        if cached && !expired?(cached[:timestamp])
+          return cached[:value]
+        end
+
+        result = @checker.available?(binary_name)
+        @cache[key] = {value: result, timestamp: Time.now}
+        result
+      end
+
+      def path_for(binary_name)
+        key = binary_name.to_s
+        cached = @path_cache[key]
+
+        if cached && !expired?(cached[:timestamp])
+          return cached[:value]
+        end
+
+        result = @checker.path_for(binary_name)
+        @path_cache[key] = {value: result, timestamp: Time.now}
+        result
+      end
+
+      # Clear all cached results.
+      # @return [void]
+      def clear_cache!
+        @cache.clear
+        @path_cache.clear
+      end
+
+      # Clear cached result for a specific binary.
+      # @param binary_name [String] the binary name to clear
+      # @return [void]
+      def clear!(binary_name)
+        key = binary_name.to_s
+        @cache.delete(key)
+        @path_cache.delete(key)
+      end
+
+      private
+
+      def expired?(timestamp)
+        Time.now - timestamp > @ttl
+      end
+    end
+
+    # AidpBinaryChecker wraps Aidp::Util.which for compatibility.
+    # This adapter bridges the BinaryCheckerInterface to AIDP's existing utility.
+    #
+    # @example Creating an adapter
+    #   checker = AidpBinaryChecker.new
+    #   provider = SomeProvider.new(binary_checker: checker)
+    #
+    class AidpBinaryChecker
+      include BinaryCheckerInterface
+
+      def available?(binary_name)
+        !Aidp::Util.which(binary_name).nil?
+      end
+
+      def path_for(binary_name)
+        Aidp::Util.which(binary_name)
+      end
+    end
+  end
+end

data/lib/aidp/interfaces/command_executor_interface.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Interfaces
+    # CommandExecutorInterface defines the contract for executing shell commands.
+    # This interface allows for dependency injection of different command execution
+    # backends, facilitating extraction of provider code into standalone gems.
+    #
+    # @example Implementing the interface
+    #   class MyExecutor
+    #     include Aidp::Interfaces::CommandExecutorInterface
+    #
+    #     def execute(command, args: [], input: nil, timeout: nil, **options)
+    #       # Implementation here
+    #       CommandResult.new(stdout: "output", stderr: "", exit_status: 0)
+    #     end
+    #   end
+    #
+    # @example Using an injected executor
+    #   class Provider
+    #     def initialize(executor: Aidp::Interfaces::TtyCommandExecutor.new)
+    #       @executor = executor
+    #     end
+    #
+    #     def run_cli(command, args)
+    #       @executor.execute(command, args: args, timeout: 30)
+    #     end
+    #   end
+    #
+    module CommandExecutorInterface
+      # Execute a shell command.
+      #
+      # @param command [String] the command to execute (e.g., "claude", "cursor-agent")
+      # @param args [Array<String>] command-line arguments
+      # @param input [String, nil] input to pass to stdin (or file path to read from)
+      # @param timeout [Integer, nil] timeout in seconds
+      # @param options [Hash] additional options (env vars, working directory, etc.)
+      # @return [CommandResult] the result of the command execution
+      # @raise [CommandTimeoutError] if the command times out
+      # @raise [CommandExecutionError] if the command fails to execute
+      def execute(command, args: [], input: nil, timeout: nil, **options)
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+    end
+
+    # Result object returned by command execution.
+    # Immutable value object containing stdout, stderr, and exit status.
+    #
+    # @example Creating a result
+    #   result = CommandResult.new(stdout: "Hello", stderr: "", exit_status: 0)
+    #   result.success? # => true
+    #   result.out      # => "Hello"
+    #
+    class CommandResult
+      attr_reader :stdout, :stderr, :exit_status
+
+      # @param stdout [String] standard output from the command
+      # @param stderr [String] standard error from the command
+      # @param exit_status [Integer] exit status code
+      def initialize(stdout:, stderr:, exit_status:)
+        @stdout = stdout.to_s.freeze
+        @stderr = stderr.to_s.freeze
+        @exit_status = exit_status.to_i
+        freeze
+      end
+
+      # @return [Boolean] true if exit_status is 0
+      def success?
+        @exit_status.zero?
+      end
+
+      # Alias for stdout for compatibility with TTY::Command::Result
+      # @return [String]
+      def out
+        @stdout
+      end
+
+      # Alias for stderr for compatibility with TTY::Command::Result
+      # @return [String]
+      def err
+        @stderr
+      end
+    end
+
+    # Error raised when a command times out.
+    class CommandTimeoutError < StandardError
+      attr_reader :command, :timeout
+
+      def initialize(command:, timeout:)
+        @command = command
+        @timeout = timeout
+        super("Command '#{command}' timed out after #{timeout} seconds")
+      end
+    end
+
+    # Error raised when command execution fails.
+    class CommandExecutionError < StandardError
+      attr_reader :command, :original_error
+
+      def initialize(command:, original_error:)
+        @command = command
+        @original_error = original_error
+        super("Command '#{command}' failed: #{original_error.message}")
+      end
+    end
+
+    # NullExecutor implements CommandExecutorInterface as a no-op.
+    # Returns successful empty results. Useful for testing.
+    #
+    # @example Using as a test double
+    #   provider = Provider.new(executor: NullExecutor.new)
+    #
+    class NullExecutor
+      include CommandExecutorInterface
+
+      def execute(command, args: [], input: nil, timeout: nil, **options)
+        CommandResult.new(stdout: "", stderr: "", exit_status: 0)
+      end
+    end
+
+    # TtyCommandExecutor wraps TTY::Command for command execution.
+    # This adapter provides the standard implementation used by AIDP.
+    #
+    # @example Creating an executor with a logger
+    #   logger = AidpLoggerAdapter.new
+    #   executor = TtyCommandExecutor.new(logger: logger)
+    #
+    class TtyCommandExecutor
+      include CommandExecutorInterface
+
+      # @param logger [LoggerInterface] optional logger for debug output
+      # @param component_name [String] component name for logging
+      def initialize(logger: nil, component_name: "command_executor")
+        @logger = logger
+        @component_name = component_name
+      end
+
+      # Execute a shell command using TTY::Command.
+      #
+      # @param command [String] the command to execute
+      # @param args [Array<String>] command-line arguments
+      # @param input [String, nil] input to pass to stdin (or file path to read from)
+      # @param timeout [Integer, nil] timeout in seconds
+      # @param options [Hash] additional options passed to TTY::Command#run
+      # @return [CommandResult] the result of the command execution
+      def execute(command, args: [], input: nil, timeout: nil, **options)
+        require "tty-command"
+
+        log_debug("executing_command", command: command, args: args, timeout: timeout)
+
+        start_time = Time.now
+
+        begin
+          cmd_obj = TTY::Command.new(printer: :null)
+
+          # Prepare input data
+          input_data = resolve_input(input)
+
+          # Execute command - use run! to get result even on non-zero exit
+          result = cmd_obj.run!(command, *args, input: input_data, timeout: timeout, **options)
+
+          duration = Time.now - start_time
+          log_debug("command_completed",
+            command: command,
+            exit_status: result.exit_status,
+            duration: duration.round(2))
+
+          CommandResult.new(
+            stdout: result.out,
+            stderr: result.err,
+            exit_status: result.exit_status
+          )
+        rescue TTY::Command::TimeoutExceeded
+          duration = Time.now - start_time
+          log_debug("command_timeout",
+            command: command,
+            timeout: timeout,
+            duration: duration.round(2))
+          raise CommandTimeoutError.new(command: command, timeout: timeout)
+        rescue Errno::ENOENT, Errno::EACCES => e
+          # Command not found or not executable
+          duration = Time.now - start_time
+          log_debug("command_not_found",
+            command: command,
+            error: e.message,
+            duration: duration.round(2))
+          raise CommandExecutionError.new(command: command, original_error: e)
+        rescue => e
+          duration = Time.now - start_time
+          log_debug("command_failed",
+            command: command,
+            error: e.message,
+            duration: duration.round(2))
+          raise CommandExecutionError.new(command: command, original_error: e)
+        end
+      end
+
+      private
+
+      def resolve_input(input)
+        return nil unless input
+
+        if input.is_a?(String) && File.exist?(input)
+          log_debug("reading_input_file", path: input)
+          File.read(input)
+        else
+          input
+        end
+      end
+
+      def log_debug(message, **metadata)
+        @logger&.log_debug(@component_name, message, **metadata)
+      end
+    end
+  end
+end

data/lib/aidp/interfaces/logger_interface.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Interfaces
+    # LoggerInterface defines the contract for logging implementations.
+    # This interface allows for dependency injection of different logging
+    # backends, facilitating extraction of provider code into standalone gems.
+    #
+    # All logging methods follow a consistent signature:
+    #   log_<level>(component, message, **metadata)
+    #
+    # Where:
+    #   - component: String identifying the subsystem (e.g., "anthropic_provider")
+    #   - message: String describing the event (e.g., "rate_limit_detected")
+    #   - metadata: Optional keyword arguments for structured logging context
+    #
+    # @example Implementing the interface
+    #   class MyLogger
+    #     include Aidp::Interfaces::LoggerInterface
+    #
+    #     def log_debug(component, message, **metadata)
+    #       puts "[DEBUG] #{component}: #{message} #{metadata}"
+    #     end
+    #
+    #     def log_info(component, message, **metadata)
+    #       puts "[INFO] #{component}: #{message} #{metadata}"
+    #     end
+    #
+    #     def log_warn(component, message, **metadata)
+    #       puts "[WARN] #{component}: #{message} #{metadata}"
+    #     end
+    #
+    #     def log_error(component, message, **metadata)
+    #       puts "[ERROR] #{component}: #{message} #{metadata}"
+    #     end
+    #   end
+    #
+    # @example Using an injected logger
+    #   class Provider
+    #     def initialize(logger: Aidp::Interfaces::NullLogger.new)
+    #       @logger = logger
+    #     end
+    #
+    #     def perform_action
+    #       @logger.log_debug("provider", "action_started", action: "perform")
+    #     end
+    #   end
+    #
+    module LoggerInterface
+      # Log a debug-level message.
+      # Use for detailed diagnostic information useful during development.
+      #
+      # @param component [String] the subsystem or module name
+      # @param message [String] the log message
+      # @param metadata [Hash] optional structured key-value pairs
+      # @return [void]
+      def log_debug(component, message, **metadata)
+        raise NotImplementedError, "#{self.class} must implement #log_debug"
+      end
+
+      # Log an info-level message.
+      # Use for general operational events that don't indicate problems.
+      #
+      # @param component [String] the subsystem or module name
+      # @param message [String] the log message
+      # @param metadata [Hash] optional structured key-value pairs
+      # @return [void]
+      def log_info(component, message, **metadata)
+        raise NotImplementedError, "#{self.class} must implement #log_info"
+      end
+
+      # Log a warning-level message.
+      # Use for potentially problematic situations that don't prevent operation.
+      #
+      # @param component [String] the subsystem or module name
+      # @param message [String] the log message
+      # @param metadata [Hash] optional structured key-value pairs
+      # @return [void]
+      def log_warn(component, message, **metadata)
+        raise NotImplementedError, "#{self.class} must implement #log_warn"
+      end
+
+      # Log an error-level message.
+      # Use for error events that might still allow operation to continue.
+      #
+      # @param component [String] the subsystem or module name
+      # @param message [String] the log message
+      # @param metadata [Hash] optional structured key-value pairs
+      # @return [void]
+      def log_error(component, message, **metadata)
+        raise NotImplementedError, "#{self.class} must implement #log_error"
+      end
+    end
+
+    # NullLogger implements LoggerInterface as a no-op.
+    # Useful as a default when no logging is required.
+    #
+    # @example Using as a default
+    #   def initialize(logger: NullLogger.new)
+    #     @logger = logger
+    #   end
+    #
+    class NullLogger
+      include LoggerInterface
+
+      def log_debug(component, message, **metadata)
+        # no-op
+      end
+
+      def log_info(component, message, **metadata)
+        # no-op
+      end
+
+      def log_warn(component, message, **metadata)
+        # no-op
+      end
+
+      def log_error(component, message, **metadata)
+        # no-op
+      end
+    end
+
+    # AidpLoggerAdapter wraps Aidp's module-level logging methods.
+    # This adapter bridges the LoggerInterface to AIDP's existing logging system.
+    #
+    # @example Creating an adapter
+    #   logger = AidpLoggerAdapter.new
+    #   provider = SomeProvider.new(logger: logger)
+    #
+    class AidpLoggerAdapter
+      include LoggerInterface
+
+      def log_debug(component, message, **metadata)
+        Aidp.log_debug(component, message, **metadata)
+      end
+
+      def log_info(component, message, **metadata)
+        Aidp.log_info(component, message, **metadata)
+      end
+
+      def log_warn(component, message, **metadata)
+        Aidp.log_warn(component, message, **metadata)
+      end
+
+      def log_error(component, message, **metadata)
+        Aidp.log_error(component, message, **metadata)
+      end
+    end
+  end
+end