ace-support-core 0.29.0

data/lib/ace/core/atoms/command_executor.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Ace
+  module Core
+    module Atoms
+      # Pure command execution functions with safety features
+      # Configuration is loaded from .ace-defaults/core/settings.yml
+      # and can be overridden at .ace/core/settings.yml (ADR-022)
+      module CommandExecutor
+        # Fallback timeout value if config is not available
+        DEFAULT_TIMEOUT = 30
+
+        # Maximum output size (1MB)
+        MAX_OUTPUT_SIZE = 1_048_576
+
+        module_function
+
+        # Get configured timeout from config cascade
+        # Falls back to DEFAULT_TIMEOUT if config is unavailable
+        # @return [Integer] Configured timeout in seconds
+        def configured_timeout
+          Ace::Core.get("core", "command_executor", "timeout") || DEFAULT_TIMEOUT
+        rescue
+          DEFAULT_TIMEOUT
+        end
+
+        # Execute a command with timeout and output capture
+        # @param command [String] Command to execute
+        # @param timeout [Integer] Timeout in seconds (defaults to config value)
+        # @param max_output [Integer] Maximum output size in bytes
+        # @param cwd [String] Working directory for command
+        # @return [Hash] {success: Boolean, stdout: String, stderr: String, exit_code: Integer, error: String}
+        def execute(command, timeout: nil, max_output: MAX_OUTPUT_SIZE, cwd: nil)
+          timeout ||= configured_timeout
+          return {success: false, error: "Command cannot be nil"} if command.nil?
+          return {success: false, error: "Command cannot be empty"} if command.strip.empty?
+
+          stdout_data = String.new
+          stderr_data = String.new
+          exit_status = nil
+          truncated = false
+
+          options = {}
+          options[:chdir] = cwd if cwd && Dir.exist?(cwd)
+
+          begin
+            Timeout.timeout(timeout) do
+              Open3.popen3(command, options) do |stdin, stdout, stderr, wait_thr|
+                stdin.close
+
+                # Read output with size limits
+                stdout_reader = Thread.new do
+                  Thread.current.report_on_exception = false
+                  begin
+                    stdout.each_char do |char|
+                      if stdout_data.bytesize < max_output
+                        stdout_data << char
+                      else
+                        truncated = true
+                        break
+                      end
+                    end
+                  rescue IOError
+                    # Stream was closed, this is expected on timeout
+                  end
+                end
+
+                stderr_reader = Thread.new do
+                  Thread.current.report_on_exception = false
+                  begin
+                    stderr.each_char do |char|
+                      if stderr_data.bytesize < max_output
+                        stderr_data << char
+                      else
+                        truncated = true
+                        break
+                      end
+                    end
+                  rescue IOError
+                    # Stream was closed, this is expected on timeout
+                  end
+                end
+
+                stdout_reader.join
+                stderr_reader.join
+
+                exit_status = wait_thr.value
+              end
+            end
+
+            result = {
+              success: exit_status.success?,
+              stdout: stdout_data,
+              stderr: stderr_data,
+              exit_code: exit_status.exitstatus
+            }
+
+            result[:warning] = "Output truncated (exceeded #{max_output} bytes)" if truncated
+
+            result
+          rescue Timeout::Error
+            {
+              success: false,
+              stdout: stdout_data,
+              stderr: stderr_data,
+              error: "Command timed out after #{timeout} seconds"
+            }
+          rescue Errno::ENOENT
+            {
+              success: false,
+              error: "Command not found: #{command.split.first}"
+            }
+          rescue => e
+            {
+              success: false,
+              stdout: stdout_data,
+              stderr: stderr_data,
+              error: "Command execution failed: #{e.message}"
+            }
+          end
+        end
+
+        # Execute command and return only stdout if successful
+        # @param command [String] Command to execute
+        # @param options [Hash] Execution options
+        # @return [String, nil] Command output or nil if failed
+        def capture(command, **options)
+          result = execute(command, **options)
+          result[:success] ? result[:stdout] : nil
+        end
+
+        # Check if a command is available in PATH
+        # @param command [String] Command name to check
+        # @return [Boolean] true if command is available
+        def available?(command)
+          return false if command.nil? || command.empty?
+
+          # Extract just the command name (first word)
+          cmd = command.split.first
+
+          # Check if command exists in PATH
+          ENV["PATH"].split(File::PATH_SEPARATOR).any? do |path|
+            executable = File.join(path, cmd)
+            File.executable?(executable) && !File.directory?(executable)
+          end
+        rescue
+          false
+        end
+
+        # Execute command with real-time output streaming
+        # @param command [String] Command to execute
+        # @param output_callback [Proc] Callback for output lines
+        # @param timeout [Integer] Timeout in seconds (defaults to config value)
+        # @param cwd [String] Working directory
+        # @return [Hash] {success: Boolean, exit_code: Integer, error: String}
+        def stream(command, output_callback: nil, timeout: nil, cwd: nil)
+          timeout ||= configured_timeout
+          return {success: false, error: "Command cannot be nil"} if command.nil?
+
+          options = {}
+          options[:chdir] = cwd if cwd && Dir.exist?(cwd)
+
+          exit_status = nil
+
+          begin
+            Timeout.timeout(timeout) do
+              Open3.popen2e(command, options) do |stdin, stdout_err, wait_thr|
+                stdin.close
+
+                stdout_err.each_line do |line|
+                  output_callback&.call(line.chomp)
+                end
+
+                exit_status = wait_thr.value
+              end
+            end
+
+            {
+              success: exit_status.success?,
+              exit_code: exit_status.exitstatus
+            }
+          rescue Timeout::Error
+            {
+              success: false,
+              error: "Command timed out after #{timeout} seconds"
+            }
+          rescue Errno::ENOENT
+            {
+              success: false,
+              error: "Command not found: #{command.split.first}"
+            }
+          rescue => e
+            {
+              success: false,
+              error: "Command execution failed: #{e.message}"
+            }
+          end
+        end
+
+        # Execute multiple commands in sequence
+        # @param commands [Array<String>] Commands to execute
+        # @param options [Hash] Execution options
+        # @return [Array<Hash>] Results for each command
+        def execute_batch(commands, **options)
+          return [] if commands.nil? || commands.empty?
+
+          commands.map do |command|
+            result = execute(command, **options)
+            result[:command] = command
+            result
+          end
+        end
+
+        # Build a safe command string with proper escaping
+        # @param command [String] Base command
+        # @param args [Array<String>] Arguments to add
+        # @return [String] Safe command string
+        def build_command(command, *args)
+          return nil if command.nil?
+
+          escaped_args = args.flatten.compact.map do |arg|
+            # Shell escape the argument
+            if arg.match?(/[^A-Za-z0-9_\-.,:\/@]/)
+              # Properly escape single quotes in shell arguments
+              "'#{arg.gsub("'", "'\\''")}'"
+            else
+              arg
+            end
+          end
+
+          [command, *escaped_args].join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/ace/core/atoms/config_summary.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Ace
+  # Core functionality for ACE gems
+  module Core
+    # Atomic operations - pure functions with no side effects
+    # Atoms are the building blocks for more complex operations.
+    # See ADR-011 for ATOM architecture details.
+    module Atoms
+      # ConfigSummary displays effective configuration state to stderr.
+      #
+      # Only shows values that differ from defaults, filtering sensitive keys.
+      # Output format: "Config: key=value key2=value2" (space-separated)
+      #
+      # ## Sensitive Key Filtering
+      #
+      # Keys ending with sensitive patterns are filtered out:
+      # - token, password, secret, credential, key, api_key
+      #
+      # Keys containing these patterns but NOT ending with them are shown:
+      # - max_tokens (contains "tokens" but doesn't end with it) ✓ shown
+      # - keyboard_layout (contains "key" but doesn't end with it) ✓ shown
+      # - auth_token (ends with "token") ✗ filtered
+      # - api_key (ends with "key") ✗ filtered
+      #
+      # ## Usage
+      #
+      #   ConfigSummary.display(
+      #     command: "review",
+      #     config: Gem.config,            # Effective config
+      #     defaults: Gem.default_config,   # Defaults for diffing
+      #     options: { verbose: true },     # Thor options hash
+      #     quiet: false,
+      #     summary_keys: %w[model preset] # Optional allowlist
+      #   )
+      #   # Output to stderr: "Config: model=gflash preset=pr"
+      #
+      class ConfigSummary
+        # Match keys ENDING with sensitive words (not containing them)
+        SENSITIVE_REGEX = /(_|^)(token|password|secret|credential|key|api_key)$/i
+
+        # Display configuration summary to stderr
+        #
+        # @param command [String] Command name for context
+        # @param config [Hash] Effective configuration (merged result)
+        # @param defaults [Hash] Default configuration to diff against
+        # @param options [Hash] CLI options (Thor options hash)
+        # @param quiet [Boolean] Suppress output if true
+        # @param summary_keys [Array<String>, nil] Allowlist of keys to include (nil = all non-sensitive)
+        # @return [nil]
+        #
+        # @example Basic usage
+        #   ConfigSummary.display(
+        #     command: "review",
+        #     config: { model: "gflash", format: "markdown" },
+        #     defaults: { "model" => "glite", "format" => "markdown" },
+        #     options: { verbose: true }
+        #   )
+        #   # Outputs: "Config: model=gflash verbose=true"
+        #
+        # @example With quiet mode
+        #   ConfigSummary.display(
+        #     command: "review",
+        #     config: { model: "gflash" },
+        #     defaults: {},
+        #     options: {},
+        #     quiet: true
+        #   )
+        #   # No output
+        #
+        # @example With allowlist
+        #   ConfigSummary.display(
+        #     command: "review",
+        #     config: { model: "gflash", format: "markdown" },
+        #     defaults: {},
+        #     options: { verbose: true },
+        #     summary_keys: %w[model]
+        #   )
+        #   # Outputs: "Config: model=gflash"
+        #   # (format and verbose not in allowlist)
+        #
+        def self.display(command:, config: {}, defaults: {}, options: {}, quiet: false, summary_keys: nil)
+          return if quiet
+
+          # Only display config when verbose mode is explicitly enabled
+          return unless options[:verbose]
+
+          summary = new(command, config, defaults, options, summary_keys).build
+          warn "Config: #{summary}" unless summary.empty?
+        end
+
+        # Display configuration summary only if help was NOT requested.
+        #
+        # This is the recommended method for commands that need to show config
+        # but want to avoid polluting --help output with configuration details.
+        #
+        # @param command [String] Command name for context
+        # @param config [Hash] Effective configuration (merged result)
+        # @param defaults [Hash] Default configuration to diff against
+        # @param options [Hash] CLI options (Thor options hash)
+        # @param quiet [Boolean] Suppress output if true
+        # @param summary_keys [Array<String>, nil] Allowlist of keys to include (nil = all non-sensitive)
+        # @return [nil]
+        #
+        # @example Usage in command
+        #   def execute
+        #     # Check for help BEFORE displaying config
+        #     return show_help if help_requested?(options, args)
+        #
+        #     # Now safe to display config
+        #     ConfigSummary.display_if_needed(
+        #       command: "review",
+        #       config: Gem.config,
+        #       defaults: Gem.default_config,
+        #       options: options
+        #     )
+        #   end
+        #
+        def self.display_if_needed(command:, config: {}, defaults: {}, options: {}, quiet: false, summary_keys: nil, args: ARGV)
+          return if quiet
+          return if help_requested?(options, args)
+
+          display(command: command, config: config, defaults: defaults, options: options, summary_keys: summary_keys)
+        end
+
+        # Check if help was requested via options or arguments.
+        #
+        # @param options [Hash] CLI options hash (from Thor)
+        # @param args [Array<String>] Command arguments (defaults to ARGV for CLI context)
+        # @return [Boolean] true if help was requested
+        #
+        # @note The `args` parameter defaults to ARGV for CLI usage convenience.
+        #       In test or non-CLI contexts, pass an explicit array to avoid global state.
+        #
+        def self.help_requested?(options = {}, args = ARGV)
+          options[:help] ||
+            options[:h] ||
+            args.include?("--help") ||
+            args.include?("-h")
+        end
+
+        def initialize(command, config, defaults, options, summary_keys)
+          @command = command
+          @config = flatten_hash(config || {})
+          @defaults = flatten_hash(defaults || {})
+          @options = options || {}
+          @summary_keys = summary_keys&.map(&:to_s)
+        end
+
+        # Build the configuration summary string
+        #
+        # @return [String] Space-separated key=value pairs
+        def build
+          pairs = []
+
+          # 1. Add CLI options that were explicitly set (non-nil, non-false)
+          @options.each do |key, value|
+            next if value.nil? || value == false
+            next if sensitive_key?(key.to_s)
+            next if @summary_keys && !@summary_keys.include?(key.to_s)
+            pairs << format_pair(key, value)
+          end
+
+          # 2. Add config values that differ from defaults (if not already in options)
+          @config.each do |key, value|
+            # Skip if already shown from options (check both symbol and string)
+            next if @options.key?(key.to_sym) || @options.key?(key.to_s)
+            next if @defaults[key] == value
+            next if sensitive_key?(key)
+            next if @summary_keys && !@summary_keys.include?(key)
+            pairs << format_pair(key, value)
+          end
+
+          pairs.sort.join(" ")
+        end
+
+        private
+
+        # Flatten nested hash to dot notation
+        # { llm: { provider: "google" } } → { "llm.provider" => "google" }
+        #
+        # @param hash [Hash] Hash to flatten
+        # @param prefix [String, nil] Current key prefix
+        # @return [Hash] Flattened hash with dot-notation keys
+        def flatten_hash(hash, prefix = nil)
+          hash.each_with_object({}) do |(key, value), result|
+            full_key = prefix ? "#{prefix}.#{key}" : key.to_s
+            if value.is_a?(Hash)
+              result.merge!(flatten_hash(value, full_key))
+            else
+              result[full_key] = value
+            end
+          end
+        end
+
+        # Format a key-value pair for output
+        #
+        # @param key [String, Symbol] Key
+        # @param value [Object] Value
+        # @return [String] Formatted "key=value" string
+        def format_pair(key, value)
+          value_str = case value
+          when true then "true"
+          when Array then value.join(",")
+          else value.to_s
+          end
+          "#{key}=#{value_str}"
+        end
+
+        # Check if a key is sensitive (should be filtered)
+        #
+        # @param key [String, Symbol] Key to check
+        # @return [Boolean] true if key is sensitive
+        def sensitive_key?(key)
+          key.to_s.match?(SENSITIVE_REGEX)
+        end
+      end
+    end
+  end
+end

data/lib/ace/core/atoms/env_parser.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ace
+  module Core
+    module Atoms
+      # Pure .env file parsing functions
+      module EnvParser
+        module_function
+
+        # Parse .env file content into hash
+        # @param content [String] .env file content
+        # @return [Hash] Parsed environment variables
+        def parse(content)
+          return {} if content.nil? || content.strip.empty?
+
+          result = {}
+          lines = content.lines.map(&:strip)
+
+          lines.each do |line|
+            # Skip empty lines and comments
+            next if line.empty? || line.start_with?("#")
+
+            # Parse KEY=VALUE format
+            if (match = line.match(/\A([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\z/))
+              key = match[1]
+              value = match[2]
+
+              # Handle quoted values
+              value = unquote(value)
+
+              result[key] = value
+            end
+          end
+
+          result
+        end
+
+        # Format hash as .env content
+        # @param env_hash [Hash] Environment variables
+        # @return [String] Formatted .env content
+        def format(env_hash)
+          return "" if env_hash.nil? || env_hash.empty?
+
+          env_hash.map do |key, value|
+            formatted_value = value.to_s.include?(" ") ? %("#{value}") : value.to_s
+            "#{key}=#{formatted_value}"
+          end.join("\n")
+        end
+
+        # Validate environment variable name
+        # @param name [String] Variable name to validate
+        # @return [Boolean] true if valid
+        def valid_key?(name)
+          !name.nil? && name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        end
+
+        # Remove quotes from value if present
+        # @param value [String] Value that may be quoted
+        # @return [String] Unquoted value
+        def unquote(value)
+          return value unless value.is_a?(String)
+
+          # Handle double quotes
+          if value.start_with?('"') && value.end_with?('"')
+            value[1..-2].gsub('\\"', '"').gsub("\\n", "\n").gsub("\\\\", "\\")
+          # Handle single quotes
+          elsif value.start_with?("'") && value.end_with?("'")
+            value[1..-2]
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end