ace-support-core 0.29.0

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ace
+  module Core
+    module Atoms
+      # Pure file reading functions with safety checks
+      module FileReader
+        # Default maximum file size (1MB)
+        MAX_FILE_SIZE = 1_048_576
+
+        # Binary file detection patterns
+        BINARY_EXTENSIONS = %w[
+          .jpg .jpeg .png .gif .bmp .ico .webp .svg
+          .pdf .doc .docx .xls .xlsx .ppt .pptx
+          .zip .tar .gz .bz2 .7z .rar
+          .exe .dll .so .dylib .app
+          .mp3 .mp4 .avi .mov .wmv .flv
+          .ttf .otf .woff .woff2 .eot
+          .class .jar .war .ear
+          .pyc .pyo .o .a
+        ].freeze
+
+        module_function
+
+        # Read file with size limit
+        # @param path [String] Path to file
+        # @param max_size [Integer] Maximum file size in bytes
+        # @return [Hash] {success: Boolean, content: String, error: String}
+        def read(path, max_size: MAX_FILE_SIZE)
+          return {success: false, error: "Path cannot be nil"} if path.nil?
+
+          expanded_path = File.expand_path(path)
+
+          unless File.exist?(expanded_path)
+            return {success: false, error: "File not found: #{path}"}
+          end
+
+          unless File.file?(expanded_path)
+            return {success: false, error: "Not a file: #{path}"}
+          end
+
+          file_size = File.size(expanded_path)
+          if file_size > max_size
+            return {
+              success: false,
+              error: "File too large: #{file_size} bytes (max: #{max_size})"
+            }
+          end
+
+          if binary?(expanded_path)
+            return {
+              success: false,
+              error: "Binary file detected: #{path}"
+            }
+          end
+
+          content = File.read(expanded_path, encoding: "UTF-8")
+          {success: true, content: content, size: file_size}
+        rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+          {success: false, error: "File contains invalid UTF-8: #{path}"}
+        rescue => e
+          {success: false, error: "Failed to read file: #{e.message}"}
+        end
+
+        # Check if file exists and is readable
+        # @param path [String] Path to file
+        # @return [Boolean] true if file exists and is readable
+        def readable?(path)
+          return false if path.nil?
+
+          expanded_path = File.expand_path(path)
+          File.exist?(expanded_path) && File.file?(expanded_path) && File.readable?(expanded_path)
+        end
+
+        # Check if file appears to be binary
+        # @param path [String] Path to file
+        # @return [Boolean] true if file appears to be binary
+        def binary?(path)
+          return false if path.nil?
+
+          # Check extension first
+          ext = File.extname(path).downcase
+          return true if BINARY_EXTENSIONS.include?(ext)
+
+          # Sample first 8KB of file for null bytes
+          expanded_path = File.expand_path(path)
+          return false unless File.exist?(expanded_path)
+
+          sample_size = [File.size(expanded_path), 8192].min
+          sample = File.read(expanded_path, sample_size, mode: "rb")
+
+          # Check for null bytes (common in binary files)
+          # Also check for common binary file markers
+          return true if sample.include?("\x00")
+
+          # Check if it's mostly non-printable characters
+          # Count non-ASCII printable characters
+          non_printable = sample.bytes.count { |b| b < 32 || b > 126 }
+          printable = sample.bytes.count { |b| b >= 32 && b <= 126 }
+
+          # If more than 30% non-printable, consider it binary
+          non_printable.to_f / (non_printable + printable) > 0.3
+        rescue
+          # If we can't read it, assume it might be binary
+          true
+        end
+
+        # Get file metadata
+        # @param path [String] Path to file
+        # @return [Hash] File metadata
+        def metadata(path)
+          return {exists: false} if path.nil?
+
+          expanded_path = File.expand_path(path)
+
+          unless File.exist?(expanded_path)
+            return {exists: false, path: path}
+          end
+
+          stat = File.stat(expanded_path)
+
+          {
+            exists: true,
+            path: path,
+            absolute_path: expanded_path,
+            size: stat.size,
+            modified: stat.mtime,
+            created: stat.ctime,
+            readable: File.readable?(expanded_path),
+            writable: File.writable?(expanded_path),
+            directory: stat.directory?,
+            file: stat.file?,
+            binary: binary?(expanded_path)
+          }
+        rescue => e
+          {exists: false, path: path, error: e.message}
+        end
+
+        # Read lines from file with line limit
+        # @param path [String] Path to file
+        # @param limit [Integer] Maximum number of lines
+        # @param offset [Integer] Starting line number (0-based)
+        # @return [Hash] {success: Boolean, lines: Array, total_lines: Integer, error: String}
+        def read_lines(path, limit: 100, offset: 0)
+          return {success: false, error: "Path cannot be nil"} if path.nil?
+
+          expanded_path = File.expand_path(path)
+
+          unless File.exist?(expanded_path)
+            return {success: false, error: "File not found: #{path}"}
+          end
+
+          if binary?(expanded_path)
+            return {success: false, error: "Binary file detected: #{path}"}
+          end
+
+          lines = []
+          total_lines = 0
+
+          File.foreach(expanded_path, encoding: "UTF-8").with_index do |line, index|
+            total_lines = index + 1
+            if index >= offset && lines.size < limit
+              lines << line.chomp
+            end
+          end
+
+          {
+            success: true,
+            lines: lines,
+            total_lines: total_lines,
+            offset: offset,
+            limit: limit
+          }
+        rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+          {success: false, error: "File contains invalid UTF-8: #{path}"}
+        rescue => e
+          {success: false, error: "Failed to read lines: #{e.message}"}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ace
+  module Core
+    module Atoms
+      # Pure glob pattern expansion and file matching functions
+      module GlobExpander
+        module_function
+
+        # Expand glob pattern to file paths
+        # @param pattern [String] Glob pattern
+        # @param base_dir [String] Base directory for relative patterns
+        # @param flags [Integer] File::FNM_* flags for matching
+        # @return [Array<String>] Matched file paths
+        def expand(pattern, base_dir: Dir.pwd, flags: 0)
+          return [] if pattern.nil? || pattern.empty?
+
+          # Ensure base_dir is absolute
+          base_dir = File.expand_path(base_dir)
+
+          # Handle absolute patterns
+          if pattern.start_with?("/")
+            Dir.glob(pattern, flags).sort
+          else
+            # Make pattern relative to base_dir
+            full_pattern = File.join(base_dir, pattern)
+            Dir.glob(full_pattern, flags).map do |path|
+              # Return relative paths from base_dir
+              Pathname.new(path).relative_path_from(Pathname.new(base_dir)).to_s
+            rescue ArgumentError
+              # If we can't make it relative, return absolute
+              path
+            end.sort
+          end
+        rescue
+          []
+        end
+
+        # Expand multiple glob patterns
+        # @param patterns [Array<String>] Array of glob patterns
+        # @param base_dir [String] Base directory for relative patterns
+        # @param flags [Integer] File::FNM_* flags for matching
+        # @return [Array<String>] Unique sorted file paths
+        def expand_multiple(patterns, base_dir: Dir.pwd, flags: 0)
+          return [] if patterns.nil? || patterns.empty?
+
+          patterns = Array(patterns)
+          results = []
+
+          patterns.each do |pattern|
+            results.concat(expand(pattern, base_dir: base_dir, flags: flags))
+          end
+
+          results.uniq.sort
+        end
+
+        # Check if path matches any of the patterns
+        # @param path [String] File path to check
+        # @param patterns [Array<String>] Patterns to match against
+        # @param flags [Integer] File::FNM_* flags for matching
+        # @return [Boolean] true if path matches any pattern
+        def matches?(path, patterns, flags: File::FNM_PATHNAME)
+          return false if path.nil? || patterns.nil?
+
+          patterns = Array(patterns)
+          patterns.any? do |pattern|
+            File.fnmatch(pattern, path, flags)
+          end
+        end
+
+        # Filter paths by exclusion patterns
+        # @param paths [Array<String>] Paths to filter
+        # @param exclude_patterns [Array<String>] Patterns to exclude
+        # @param flags [Integer] File::FNM_* flags for matching
+        # @return [Array<String>] Filtered paths
+        def filter_excluded(paths, exclude_patterns, flags: File::FNM_PATHNAME)
+          return paths if paths.nil? || exclude_patterns.nil? || exclude_patterns.empty?
+
+          paths.reject do |path|
+            matches?(path, exclude_patterns, flags: flags)
+          end
+        end
+
+        # Expand pattern with exclusions
+        # @param pattern [String] Glob pattern to expand
+        # @param exclude [Array<String>] Patterns to exclude
+        # @param base_dir [String] Base directory
+        # @return [Array<String>] Matched paths excluding excluded ones
+        def expand_with_exclusions(pattern, exclude: [], base_dir: Dir.pwd)
+          expanded = expand(pattern, base_dir: base_dir)
+          return expanded if exclude.nil? || exclude.empty?
+
+          filter_excluded(expanded, exclude)
+        end
+
+        # Find files recursively with pattern
+        # @param pattern [String] File name pattern
+        # @param base_dir [String] Starting directory
+        # @param max_depth [Integer] Maximum directory depth (nil for unlimited)
+        # @return [Array<String>] Found file paths
+        def find_files(pattern, base_dir: Dir.pwd, max_depth: nil)
+          return [] if pattern.nil?
+
+          base_dir = File.expand_path(base_dir)
+          results = []
+
+          # Build the glob pattern based on depth
+          if max_depth.nil?
+            glob_pattern = File.join(base_dir, "**", pattern)
+          else
+            # Build pattern with limited depth
+            depth_pattern = (0..max_depth).map do |depth|
+              parts = ["*"] * depth
+              File.join(base_dir, *parts, pattern)
+            end
+
+            depth_pattern.each do |p|
+              results.concat(Dir.glob(p))
+            end
+
+            return results.map do |path|
+              Pathname.new(path).relative_path_from(Pathname.new(base_dir)).to_s
+            rescue ArgumentError
+              path
+            end.uniq.sort
+          end
+
+          Dir.glob(glob_pattern).map do |path|
+            Pathname.new(path).relative_path_from(Pathname.new(base_dir)).to_s
+          rescue ArgumentError
+            path
+          end.sort
+        end
+
+        # Check if pattern is a glob pattern
+        # @param pattern [String] Pattern to check
+        # @return [Boolean] true if pattern contains glob characters
+        def glob_pattern?(pattern)
+          return false if pattern.nil?
+
+          pattern.match?(/[*?\[{]/)
+        end
+
+        # Normalize path separators for current OS
+        # @param path [String] Path to normalize
+        # @return [String] Normalized path
+        def normalize_separators(path)
+          return nil if path.nil?
+
+          path.gsub(/[\\\/]+/, File::SEPARATOR)
+        end
+
+        # Convert glob pattern to regex
+        # @param pattern [String] Glob pattern
+        # @return [Regexp] Regular expression equivalent
+        def to_regex(pattern)
+          return nil if pattern.nil?
+
+          # Escape special regex characters except glob ones
+          escaped = pattern.gsub(/[.+^$()|\[\]{}\\]/) { |m| "\\#{m}" }
+
+          # Convert glob patterns to regex
+          regex_pattern = escaped
+            .gsub("**/", ".*/")      # ** matches any depth
+            .gsub("*", "[^/]*")       # * matches within directory
+            .tr("?", ".")           # ? matches single character
+
+          Regexp.new("^#{regex_pattern}$")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ace
+  module Core
+    module Atoms
+      # Pure functions for process termination with graceful fallback to force kill
+      module ProcessTerminator
+        module_function
+
+        # Terminate a process gracefully, then forcefully if needed
+        #
+        # Sends SIGTERM first to allow graceful shutdown, then SIGKILL if process
+        # still exists after a brief wait. Silently handles cases where the process
+        # has already terminated or is inaccessible.
+        #
+        # @param pid [Integer, nil] Process ID to terminate
+        # @param grace_period [Float] Seconds to wait between TERM and KILL (default: 0.1)
+        # @return [Boolean] true if termination was attempted, false if pid was nil
+        def terminate(pid, grace_period: 0.1)
+          return false unless pid
+
+          begin
+            # Try graceful termination first (SIGTERM)
+            Process.kill("TERM", pid)
+            # Give it a moment to terminate
+            sleep(grace_period)
+            # Check if still running and force kill if needed
+            Process.kill(0, pid) # Check if process exists
+            Process.kill("KILL", pid)
+          rescue Errno::ESRCH, Errno::EPERM
+            # Process already terminated or we don't have permission - that's fine
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Core
+    module Atoms
+      # Pure template parsing functions for context configurations
+      module TemplateParser
+        # Valid template configuration keys
+        VALID_KEYS = %w[
+          files commands format embed_document_source
+          include exclude output max_lines max_size timeout
+        ].freeze
+
+        module_function
+
+        # Parse template configuration from string
+        # @param content [String] Template content (YAML or markdown with embedded YAML)
+        # @return [Hash] {success: Boolean, config: Hash, error: String}
+        def parse(content)
+          return {success: false, error: "Content cannot be nil"} if content.nil?
+          return {success: false, error: "Content cannot be empty"} if content.strip.empty?
+
+          # Try to extract from markdown with tags first
+          config = extract_from_markdown(content)
+
+          # If not found, try to parse as direct YAML
+          config ||= parse_yaml(content)
+
+          if config.nil?
+            return {success: false, error: "No valid configuration found"}
+          end
+
+          validate_config(config)
+        rescue => e
+          {success: false, error: "Failed to parse template: #{e.message}"}
+        end
+
+        # Extract configuration from markdown with <context-tool-config> tags
+        # @param content [String] Markdown content
+        # @return [Hash, nil] Extracted configuration or nil
+        def extract_from_markdown(content)
+          return nil if content.nil?
+
+          # Look for <context-tool-config> block
+          pattern = /<context-tool-config>\s*\n(.*?)\n<\/context-tool-config>/m
+          match = content.match(pattern)
+
+          return nil unless match
+
+          yaml_content = match[1]
+          parse_yaml(yaml_content)
+        end
+
+        # Extract configuration from agent markdown files
+        # @param content [String] Agent markdown content
+        # @return [Hash, nil] Extracted configuration or nil
+        def extract_from_agent(content)
+          return nil if content.nil?
+
+          # Look for Context Definition section
+          context_match = content.match(/^## Context Definition\s*\n(.*?)(?=^## |\z)/m)
+          return nil unless context_match
+
+          context_section = context_match[1].strip
+
+          # Extract YAML from code block
+          yaml_match = context_section.match(/```(?:yaml|yml)?\s*\n(.*?)\n```/m)
+          return nil unless yaml_match
+
+          yaml_content = yaml_match[1]
+          parse_yaml(yaml_content)
+        end
+
+        # Parse YAML string to hash
+        # @param yaml_string [String] YAML content
+        # @return [Hash, nil] Parsed configuration or nil
+        def parse_yaml(yaml_string)
+          return nil if yaml_string.nil? || yaml_string.strip.empty?
+
+          result = YAML.safe_load(yaml_string, permitted_classes: [Symbol])
+
+          # Ensure it's a hash
+          result.is_a?(Hash) ? stringify_keys(result) : nil
+        rescue Psych::SyntaxError
+          nil
+        end
+
+        # Validate configuration structure
+        # @param config [Hash] Configuration to validate
+        # @return [Hash] {success: Boolean, config: Hash, error: String}
+        def validate_config(config)
+          return {success: false, error: "Config must be a Hash"} unless config.is_a?(Hash)
+
+          # Check for unknown keys
+          unknown_keys = config.keys - VALID_KEYS
+          unless unknown_keys.empty?
+            return {
+              success: false,
+              error: "Unknown configuration keys: #{unknown_keys.join(", ")}"
+            }
+          end
+
+          # Normalize arrays
+          normalized = normalize_config(config)
+
+          # Validate required content
+          if normalized["files"].empty? && normalized["commands"].empty? &&
+              normalized["include"].empty?
+            return {
+              success: false,
+              error: "Configuration must specify 'files', 'commands', or 'include'"
+            }
+          end
+
+          {success: true, config: normalized}
+        end
+
+        # Normalize configuration values
+        # @param config [Hash] Configuration to normalize
+        # @return [Hash] Normalized configuration
+        def normalize_config(config)
+          {
+            "files" => to_array(config["files"]),
+            "commands" => to_array(config["commands"]),
+            "include" => to_array(config["include"]),
+            "exclude" => to_array(config["exclude"]),
+            "format" => config["format"],
+            "embed_document_source" => config["embed_document_source"],
+            "output" => config["output"],
+            "max_lines" => config["max_lines"],
+            "max_size" => config["max_size"],
+            "timeout" => config["timeout"]
+          }.compact
+        end
+
+        # Convert value to array
+        # @param value [nil, String, Array] Value to convert
+        # @return [Array] Array of strings
+        def to_array(value)
+          case value
+          when nil
+            []
+          when Array
+            value.map(&:to_s)
+          when String
+            [value]
+          else
+            [value.to_s]
+          end
+        end
+
+        # Merge multiple configurations
+        # @param configs [Array<Hash>] Configurations to merge
+        # @return [Hash] Merged configuration
+        def merge_configs(*configs)
+          configs = configs.flatten.compact
+
+          return {} if configs.empty?
+
+          result = {
+            "files" => [],
+            "commands" => [],
+            "include" => [],
+            "exclude" => []
+          }
+
+          configs.each do |config|
+            next unless config.is_a?(Hash)
+
+            # Concatenate arrays
+            %w[files commands include exclude].each do |key|
+              result[key].concat(to_array(config[key]))
+            end
+
+            # Take last non-nil value for other keys
+            %w[format embed_document_source output max_lines max_size timeout].each do |key|
+              result[key] = config[key] if config.key?(key)
+            end
+          end
+
+          # Remove duplicates from arrays
+          %w[files commands include exclude].each do |key|
+            result[key].uniq!
+          end
+
+          result.compact
+        end
+
+        # Check if content appears to be a template
+        # @param content [String] Content to check
+        # @return [Boolean] true if content looks like a template
+        def template?(content)
+          return false if content.nil?
+
+          # Check for various template indicators
+          content.include?("<context-tool-config>") ||
+            content.match?(/^files:\s*$/m) ||
+            content.match?(/^commands:\s*$/m) ||
+            content.match?(/^include:\s*$/m) ||
+            content.match?(/^## Context Definition/m)
+        end
+
+        private
+
+        # Convert all keys to strings recursively
+        # @param hash [Hash] Hash with potentially mixed keys
+        # @return [Hash] Hash with string keys
+        module_function
+
+        def stringify_keys(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = value.is_a?(Hash) ? stringify_keys(value) : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/core/cli/config_summary_mixin.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../atoms/config_summary"
+
+module Ace
+  module Core
+    module CLI
+      module ConfigSummaryMixin
+        include Ace::Support::Cli::Base
+
+        def display_config_summary(command_name, options, summary_keys: nil)
+          return if quiet?(options)
+
+          Ace::Core::Atoms::ConfigSummary.display(
+            command: command_name,
+            config: gem_config,
+            defaults: gem_defaults,
+            options: options,
+            quiet: false,
+            summary_keys: summary_keys
+          )
+        end
+
+        def help_requested?(options)
+          help?(options)
+        end
+
+        private
+
+        def gem_config
+          raise NotImplementedError, "#{self.class} must implement #gem_config"
+        end
+
+        def gem_defaults
+          raise NotImplementedError, "#{self.class} must implement #gem_defaults"
+        end
+
+        module GemClassMixin
+          include ConfigSummaryMixin
+
+          private
+
+          def gem_config
+            self.class.gem_class.config
+          end
+
+          def gem_defaults
+            self.class.gem_class.default_config
+          end
+        end
+      end
+    end
+  end
+end