ace-support-core 0.29.0

data/lib/ace/core/cli.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "organisms/config_initializer"
+require_relative "organisms/config_diff"
+require_relative "models/config_templates"
+
+module Ace
+  module Core
+    # Framework CLI for ace-framework binary.
+    # Uses a separate class name to avoid collision with Ace::Core::CLI module
+    # (which provides shared CLI infrastructure).
+    class FrameworkCLI
+      def self.start(argv)
+        new.run(argv)
+      end
+
+      def run(argv)
+        return show_help if argv.empty?
+
+        command = argv.shift
+
+        case command
+        when "init"
+          run_init(argv)
+        when "diff"
+          run_diff(argv)
+        when "list"
+          run_list(argv)
+        when "version", "--version"
+          show_version
+        when "help", "--help", "-h"
+          show_help
+        else
+          puts "Unknown command: #{command}"
+          puts ""
+          show_help
+          exit 1
+        end
+      end
+
+      private
+
+      def run_init(argv)
+        options = {}
+
+        parser = OptionParser.new do |opts|
+          opts.banner = <<~BANNER.chomp
+            NAME
+              ace-framework init - Initialize configuration for ace-* gems
+
+            USAGE
+              ace-framework init [GEM] [OPTIONS]
+
+            OPTIONS
+          BANNER
+          opts.on("--force", "Overwrite existing files") { options[:force] = true }
+          opts.on("--dry-run", "Show what would be done") { options[:dry_run] = true }
+          opts.on("--global", "Use ~/.ace instead of ./.ace") { options[:global] = true }
+          opts.on("--verbose", "Show verbose output") { options[:verbose] = true }
+          opts.on("-h", "--help", "Show this help") {
+            puts opts
+            exit
+          }
+        end
+
+        parser.parse!(argv)
+        gem_name = argv.shift
+
+        initializer = ConfigInitializer.new(**options)
+
+        if gem_name
+          initializer.init_gem(gem_name)
+        else
+          initializer.init_all
+        end
+      end
+
+      def run_diff(argv)
+        options = {}
+
+        parser = OptionParser.new do |opts|
+          opts.banner = <<~BANNER.chomp
+            NAME
+              ace-framework diff - Compare configs with examples
+
+            USAGE
+              ace-framework diff [GEM] [OPTIONS]
+
+            OPTIONS
+          BANNER
+          opts.on("--global", "Compare global configs") { options[:global] = true }
+          opts.on("--local", "Compare local configs (default)") { options[:local] = true }
+          opts.on("--file PATH", "Compare specific file") { |f| options[:file] = f }
+          opts.on("--one-line", "One-line summary per file") { options[:one_line] = true }
+          opts.on("-h", "--help", "Show this help") {
+            puts opts
+            exit
+          }
+        end
+
+        parser.parse!(argv)
+        gem_name = argv.shift
+
+        differ = ConfigDiff.new(**options)
+
+        if gem_name
+          differ.diff_gem(gem_name)
+        else
+          differ.run
+        end
+      end
+
+      def run_list(argv)
+        verbose = false
+
+        parser = OptionParser.new do |opts|
+          opts.banner = <<~BANNER.chomp
+            NAME
+              ace-framework list - List available ace-* gems with example configs
+
+            USAGE
+              ace-framework list [OPTIONS]
+
+            OPTIONS
+          BANNER
+          opts.on("--verbose", "Show detailed information") { verbose = true }
+          opts.on("-h", "--help", "Show this help") {
+            puts opts
+            exit
+          }
+        end
+
+        parser.parse!(argv)
+
+        puts "Available ace-* gems with example configurations:\n\n"
+
+        if ConfigTemplates.all_gems.empty?
+          puts "No ace-* gems with example configurations found."
+          return
+        end
+
+        ConfigTemplates.all_gems.each do |gem_name|
+          info = ConfigTemplates.gem_info[gem_name]
+          source_label = case info[:source]
+          when :local then "[local]"
+          when :gem then "[gem]"
+          when :both then "[local+gem]"
+          end
+
+          puts "  #{gem_name} #{source_label}"
+
+          if verbose
+            puts "    Path: #{info[:path]}"
+            puts "    Gem: #{info[:gem_path]}" if info[:gem_path]
+            example_dir = ConfigTemplates.example_dir_for(gem_name)
+            if example_dir && File.exist?(example_dir)
+              example_files = Dir.glob("#{example_dir}/**/*").reject { |f| File.directory?(f) }
+              puts "    Example files: #{example_files.size}"
+            end
+          end
+        end
+
+        puts "\nUse 'ace-framework init [GEM]' to initialize a specific gem's configuration"
+        puts "Use 'ace-framework init' to initialize all configurations"
+      end
+
+      def show_version
+        puts "ace-framework #{Ace::Core::VERSION}"
+      end
+
+      def show_help
+        puts <<~HELP
+          NAME
+            ace-framework - Configuration management for ace-* gems
+
+          USAGE
+            ace-framework COMMAND [OPTIONS]
+
+          COMMANDS
+            init [GEM]                        Initialize configuration for specific gem or all
+            diff [GEM]                        Compare configs with examples
+            list                              List available ace-* gems with example configs
+            version                           Show version
+            help                              Show this help
+
+          Run 'ace-framework COMMAND --help' for more information on a command.
+        HELP
+      end
+    end
+  end
+end

data/lib/ace/core/config_discovery.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+require "ace/support/fs"
+
+module Ace
+  module Core
+    # Public API for configuration discovery across the project hierarchy
+    # Wraps ace-config with ace-specific defaults (.ace config directory)
+    class ConfigDiscovery
+      attr_reader :start_path
+
+      # Initialize config discovery
+      # @param start_path [String] Starting path for discovery (default: current directory)
+      def initialize(start_path: nil)
+        @start_path = start_path || Dir.pwd
+        @finder = ::Ace::Support::Config::Molecules::ConfigFinder.new(
+          config_dir: ".ace",
+          defaults_dir: ".ace-defaults",
+          use_traversal: true,
+          start_path: @start_path
+        )
+      end
+
+      # Find the first matching config file in the cascade
+      # @param filename [String] Config filename to find
+      # @return [String, nil] Path to the config file or nil if not found
+      def find_config_file(filename)
+        @finder.find_file(filename)
+      end
+
+      # Find all matching config files in cascade order
+      # @param filename [String] Config filename to find
+      # @return [Array<String>] All matching file paths in priority order
+      def find_all_config_files(filename)
+        @finder.find_all_files(filename)
+      end
+
+      # Get the project root directory
+      # @return [String, nil] Project root path or nil if not in a project
+      def project_root
+        ::Ace::Support::Fs::Molecules::ProjectRootFinder.find(start_path: @start_path)
+      end
+
+      # Check if we're in a project
+      # @return [Boolean] true if project root is found
+      def in_project?
+        !project_root.nil?
+      end
+
+      # Get all configuration search paths in order
+      # @return [Array<String>] Ordered list of config directories being searched
+      def config_search_paths
+        @finder.search_paths
+      end
+
+      # Get relative path from project root
+      # @param path [String] Path to make relative
+      # @return [String, nil] Relative path or nil if not in project
+      def relative_path(path)
+        root = project_root
+        return nil unless root
+
+        expanded = File.expand_path(path)
+        return nil unless expanded.start_with?(root)
+
+        require "pathname"
+        Pathname.new(expanded).relative_path_from(Pathname.new(root)).to_s
+      end
+
+      # Load configuration from the cascade for a specific file
+      # @param filename [String] Config file to load
+      # @param resolve_paths [Boolean] Whether to resolve relative paths (default: true)
+      # @return [Hash, nil] Merged configuration or nil if no files found
+      def load_config(filename, resolve_paths: true)
+        files = find_all_config_files(filename)
+        return nil if files.empty?
+
+        require "yaml"
+        config = {}
+
+        # Load in reverse order so higher priority overwrites lower
+        files.reverse_each do |file|
+          file_config = YAML.load_file(file)
+          if file_config.is_a?(Hash)
+            # Resolve relative paths if requested
+            if resolve_paths
+              base_dir = File.dirname(file)
+              # Determine project root for resolving plain paths
+              proj_root = project_root
+              file_config = resolve_relative_paths(file_config, base_dir, proj_root)
+            end
+            config = ::Ace::Support::Config::Atoms::DeepMerger.merge(config, file_config)
+          end
+        rescue => e
+          warn "Error loading config from #{file}: #{e.message}"
+        end
+
+        config
+      end
+
+      # Class method shortcuts
+      class << self
+        # Find a config file from current directory
+        # @param filename [String] Config filename to find
+        # @return [String, nil] Path to config file
+        def find(filename)
+          new.find_config_file(filename)
+        end
+
+        # Find all config files from current directory
+        # @param filename [String] Config filename to find
+        # @return [Array<String>] All matching file paths
+        def find_all(filename)
+          new.find_all_config_files(filename)
+        end
+
+        # Get project root from current directory
+        # @return [String, nil] Project root path
+        def project_root
+          new.project_root
+        end
+
+        # Load merged configuration
+        # @param filename [String] Config file to load
+        # @return [Hash, nil] Merged configuration
+        def load(filename)
+          new.load_config(filename)
+        end
+      end
+
+      private
+
+      # Recursively resolve relative paths in a configuration structure
+      # @param obj [Object] Configuration object (hash, array, or value)
+      # @param base_dir [String] Base directory to resolve paths against
+      # @param project_root [String] Project root directory for plain paths
+      # @return [Object] Configuration with resolved paths
+      def resolve_relative_paths(obj, base_dir, project_root = nil)
+        case obj
+        when Hash
+          obj.transform_values { |v| resolve_relative_paths(v, base_dir, project_root) }
+        when Array
+          obj.map { |v| resolve_relative_paths(v, base_dir, project_root) }
+        when String
+          # Check if this looks like a relative path with dots
+          if obj.start_with?("./", "../")
+            # Resolve relative to the config file's directory
+            File.expand_path(File.join(base_dir, obj))
+          elsif project_root && looks_like_project_path?(obj)
+            # Plain paths that look like project directories/files
+            # are resolved relative to project root
+            File.join(project_root, obj)
+          else
+            obj
+          end
+        else
+          obj
+        end
+      end
+
+      # Check if a string looks like a project-relative path
+      # @param str [String] String to check
+      # @return [Boolean] true if it looks like a project path
+      def looks_like_project_path?(str)
+        # Don't treat absolute paths, URLs, or special values as project paths
+        return false if str.start_with?("/", "http://", "https://", "~")
+        return false if str.include?(":") # URLs, Windows paths
+
+        # Check if it looks like a path (contains slash or common project directories)
+        # or matches common project directory names
+        str.include?("/") || str.match?(/^(ace-|lib|src|bin|test|spec|app|config|vendor|node_modules)/)
+      end
+    end
+  end
+end

data/lib/ace/core/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Ace
+  module Core
+    # Base error class for all ace-core errors
+    class Error < StandardError; end
+
+    # Raised when configuration file is invalid (ace-specific)
+    class ConfigInvalidError < Error; end
+
+    # Raised when environment file parsing fails (ace-specific)
+    class EnvParseError < Error; end
+  end
+end

data/lib/ace/core/models/config_templates.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rubygems"
+
+module Ace
+  module Core
+    class ConfigTemplates
+      class << self
+        def all_gems
+          gem_info.keys.sort
+        end
+
+        def gem_exists?(gem_name)
+          gem_info.key?(gem_name)
+        end
+
+        def example_dir_for(gem_name)
+          info = gem_info[gem_name]
+          return nil unless info
+
+          # Prefer local path for development
+          path = (info[:source] == :gem) ? info[:path] : (info[:path] || info[:gem_path])
+          resolve_defaults_dir(path)
+        end
+
+        def gem_info
+          @gem_info ||= build_gem_info
+        end
+
+        def build_gem_info
+          gems = {}
+
+          # 1. Look in the parent directory (monorepo/development)
+          parent_dir = File.expand_path("../../../../../../", __FILE__)
+          Dir.glob("#{parent_dir}/ace-*").each do |dir|
+            next unless File.directory?(dir)
+            gem_name = File.basename(dir)
+            if has_example_dir?(dir)
+              gems[gem_name] = {source: :local, path: dir}
+            end
+          end
+
+          # 2. Look for installed RubyGems
+          begin
+            Gem::Specification.each do |spec|
+              next unless spec.name.start_with?("ace-")
+
+              gem_path = spec.gem_dir
+              if has_example_dir?(gem_path)
+                if gems.key?(spec.name)
+                  gems[spec.name][:source] = :both
+                  gems[spec.name][:gem_path] = gem_path
+                else
+                  gems[spec.name] = {source: :gem, path: gem_path}
+                end
+              end
+            end
+          rescue
+            # If we can't access installed gems, just use local ones
+          end
+
+          gems
+        end
+
+        def docs_file_for(gem_name)
+          info = gem_info[gem_name]
+          return nil unless info
+
+          # Prefer local path for development
+          path = (info[:source] == :gem) ? info[:path] : (info[:path] || info[:gem_path])
+          File.join(path, "docs", "config.md")
+        end
+
+        private
+
+        def resolve_defaults_dir(gem_path)
+          File.join(gem_path, ".ace-defaults")
+        end
+
+        def has_example_dir?(gem_dir)
+          Dir.exist?(File.join(gem_dir, ".ace-defaults"))
+        end
+      end
+    end
+  end
+end

data/lib/ace/core/molecules/env_loader.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/env_parser"
+require "ace/support/fs"
+require_relative "../errors"
+
+module Ace
+  module Core
+    module Molecules
+      # .env file loading and environment variable management
+      class EnvLoader
+        # Load .env file and return parsed variables
+        # @param filepath [String] Path to .env file
+        # @return [Hash] Parsed environment variables
+        # @raise [EnvParseError] if parsing fails
+        def self.load_file(filepath)
+          filepath = Ace::Support::Fs::Atoms::PathExpander.expand(filepath)
+
+          unless File.exist?(filepath)
+            return {}
+          end
+
+          content = File.read(filepath)
+          Atoms::EnvParser.parse(content)
+        rescue IOError, SystemCallError => e
+          raise EnvParseError, "Failed to read .env file #{filepath}: #{e.message}"
+        end
+
+        # Load .env file and set environment variables
+        # @param filepath [String] Path to .env file
+        # @param overwrite [Boolean] Whether to overwrite existing vars
+        # @return [Hash] Variables that were set
+        def self.load_and_set(filepath, overwrite: true)
+          vars = load_file(filepath)
+          set_environment(vars, overwrite: overwrite)
+        end
+
+        # Set environment variables from hash
+        # @param vars [Hash] Variables to set
+        # @param overwrite [Boolean] Whether to overwrite existing
+        # @return [Hash] Variables that were actually set
+        def self.set_environment(vars, overwrite: true)
+          set_vars = {}
+
+          vars.each do |key, value|
+            next unless Atoms::EnvParser.valid_key?(key)
+            next if !overwrite && ENV.key?(key)
+
+            ENV[key] = value.to_s
+            set_vars[key] = value
+          end
+
+          set_vars
+        end
+
+        # Save environment variables to .env file
+        # @param vars [Hash] Variables to save
+        # @param filepath [String] Path to .env file
+        def self.save_file(vars, filepath)
+          content = Atoms::EnvParser.format(vars)
+
+          # Create directory if it doesn't exist
+          dir = File.dirname(filepath)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          File.write(filepath, content)
+        rescue IOError, SystemCallError => e
+          raise EnvParseError, "Failed to save .env file #{filepath}: #{e.message}"
+        end
+
+        # Load multiple .env files in order
+        # @param filepaths [Array<String>] Paths to .env files
+        # @param overwrite [Boolean] Whether to overwrite existing
+        # @return [Hash] All variables that were set
+        def self.load_multiple(*filepaths, overwrite: true)
+          all_vars = {}
+
+          filepaths.flatten.each do |filepath|
+            vars = load_file(filepath)
+            all_vars.merge!(vars) if vars && !vars.empty?
+          end
+
+          set_environment(all_vars, overwrite: overwrite)
+        end
+
+        # Find and load .env files in standard locations
+        # @param root [String] Project root directory
+        # @return [Hash] Variables that were loaded
+        def self.auto_load(root = Dir.pwd)
+          root = Ace::Support::Fs::Atoms::PathExpander.expand(root)
+
+          # Standard .env file locations in priority order
+          env_files = [
+            File.join(root, ".env.local"),
+            File.join(root, ".env")
+          ]
+
+          # Load files that exist
+          existing = env_files.select { |f| File.exist?(f) }
+          load_multiple(*existing, overwrite: false) unless existing.empty?
+        end
+
+        # Load .env files from cascade without setting ENV
+        # @param search_paths [Array<String>, nil] Optional search paths
+        # @return [Hash] Merged variables from all .env files
+        def self.load_cascade(search_paths: nil)
+          require_relative "../config_discovery"
+
+          discovery = ConfigDiscovery.new(start_path: search_paths&.first)
+          merged_vars = {}
+
+          # Find all .env files in cascade (returns in priority order)
+          env_files = discovery.find_all_config_files(".env")
+
+          # Load each file and merge (later files override earlier)
+          env_files.reverse_each do |filepath|
+            next unless File.exist?(filepath)
+
+            file_vars = load_file(filepath)
+            merged_vars.merge!(file_vars) if file_vars && !file_vars.empty?
+          end
+
+          merged_vars
+        end
+      end
+    end
+  end
+end