htm 0.0.17 → 0.0.18

data/lib/htm/database.rb

@@ -11,7 +11,7 @@ class HTM
     class << self
       # Set up the HTM database schema
       #
-      # @param db_url [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+      # @param db_url [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
       # @param run_migrations [Boolean] Whether to run migrations (default: true)
       # @param dump_schema [Boolean] Whether to dump schema to db/schema.sql after setup (default: false)
       # @return [void]
@@ -40,7 +40,7 @@ class HTM
 
       # Run pending database migrations
       #
-      # @param db_url [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+      # @param db_url [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
       # @return [void]
       #
       def migrate(db_url = nil)
@@ -57,7 +57,7 @@ class HTM
 
       # Show migration status
       #
-      # @param db_url [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+      # @param db_url [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
       # @return [void]
       #
       def migration_status(db_url = nil)
@@ -158,7 +158,7 @@ class HTM
       # All seeding logic is contained in db/seeds.rb and reads data
       # from markdown files in db/seed_data/ directory.
       #
-      # @param db_url [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+      # @param db_url [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
       # @return [void]
       #
       def seed(db_url = nil)
@@ -292,7 +292,7 @@ class HTM
       # - Index information
       # - Relationship diagrams
       #
-      # @param db_url [String] Database connection URL (uses ENV['HTM_DBURL'] if not provided)
+      # @param db_url [String] Database connection URL (uses ENV['HTM_DATABASE__URL'] if not provided)
       # @return [void]
       #
       def generate_docs(db_url = nil)
@@ -319,8 +319,8 @@ class HTM
         end
 
         # Get database URL
-        dsn = db_url || ENV['HTM_DBURL']
-        raise "Database configuration not found. Set HTM_DBURL environment variable." unless dsn
+        dsn = db_url || ENV['HTM_DATABASE__URL']
+        raise "Database configuration not found. Set HTM_DATABASE__URL environment variable." unless dsn
 
         # Ensure sslmode is set for local development (tbls requires it)
         unless dsn.include?('sslmode=')
@@ -460,30 +460,29 @@ class HTM
       # @return [Hash, nil] Connection configuration hash
       #
       def parse_connection_params
-        return nil unless ENV['HTM_DBNAME']
+        return nil unless ENV['HTM_DATABASE__NAME']
 
         {
-          host: ENV['HTM_DBHOST'] || 'localhost',
-          port: (ENV['HTM_DBPORT'] || 5432).to_i,
-          dbname: ENV['HTM_DBNAME'],
-          user: ENV['HTM_DBUSER'],
-          password: ENV['HTM_DBPASS'],
-          sslmode: ENV['HTM_DBSSLMODE'] || 'prefer'
+          host: ENV['HTM_DATABASE__HOST'] || 'localhost',
+          port: (ENV['HTM_DATABASE__PORT'] || 5432).to_i,
+          dbname: ENV['HTM_DATABASE__NAME'],
+          user: ENV['HTM_DATABASE__USER'],
+          password: ENV['HTM_DATABASE__PASSWORD'],
+          sslmode: ENV['HTM_DATABASE__SSLMODE'] || 'prefer'
         }
       end
 
-      # Get default database configuration (respects RAILS_ENV)
+      # Get default database configuration
       #
-      # Uses ActiveRecordConfig which reads from config/database.yml
-      # and respects RAILS_ENV for environment-specific database selection.
+      # Uses HTM::Config for database settings.
       #
       # @return [Hash, nil] Connection configuration hash with PG-style keys
       #
       def default_config
-        require_relative 'active_record_config'
+        htm_config = HTM.config
 
-        begin
-          ar_config = HTM::ActiveRecordConfig.load_database_config
+        if htm_config.database_configured?
+          ar_config = htm_config.database_config
 
           # Convert ActiveRecord config keys to PG-style keys
           {
@@ -494,13 +493,10 @@ class HTM
             password: ar_config[:password],
             sslmode: ar_config[:sslmode] || 'prefer'
           }
-        rescue StandardError
-          # Fallback to legacy behavior if ActiveRecordConfig fails
-          if ENV['HTM_DBURL']
-            parse_connection_url(ENV['HTM_DBURL'])
-          elsif ENV['HTM_DBNAME']
-            parse_connection_params
-          end
+        elsif ENV['HTM_DATABASE__URL']
+          parse_connection_url(ENV['HTM_DATABASE__URL'])
+        elsif ENV['HTM_DATABASE__NAME']
+          parse_connection_params
         end
       end
 

data/lib/htm/embedding_service.rb

@@ -68,8 +68,6 @@ class HTM
     # @raise [CircuitBreakerOpenError] If circuit breaker is open
     #
     def self.generate(text)
-      HTM.logger.debug "EmbeddingService: Generating embedding for #{text.length} chars"
-
       # Use circuit breaker to protect against cascading failures
       raw_embedding = circuit_breaker.call do
         HTM.configuration.embedding_generator.call(text)
@@ -95,8 +93,6 @@ class HTM
       # Format for database storage
       storage_string = format_for_storage(storage_embedding)
 
-      HTM.logger.debug "EmbeddingService: Generated #{actual_dimension}D embedding (padded to #{max_dim})"
-
       {
         embedding: raw_embedding,
         dimension: actual_dimension,

data/lib/htm/integrations/sinatra.rb

@@ -138,7 +138,6 @@ class HTM
           return if @@db_config
 
           @@db_config = HTM::ActiveRecordConfig.load_database_config
-          HTM.logger.debug "HTM database config stored for thread-safe access"
         end
       end
 
@@ -160,15 +159,13 @@ class HTM
         # Re-establish connection using stored config
         if @@db_config
           ActiveRecord::Base.establish_connection(@@db_config)
-          HTM.logger.debug "HTM database connection established for request thread"
         else
           raise "HTM database config not stored - call register_htm at app startup"
         end
-      rescue ActiveRecord::ConnectionNotDefined, ActiveRecord::ConnectionNotEstablished => e
+      rescue ActiveRecord::ConnectionNotDefined, ActiveRecord::ConnectionNotEstablished
         # Pool doesn't exist, establish connection
         if @@db_config
           ActiveRecord::Base.establish_connection(@@db_config)
-          HTM.logger.debug "HTM database connection established for request thread"
         else
           raise "HTM database config not stored - call register_htm at app startup"
         end
@@ -209,9 +206,9 @@ module ::Sinatra
 
         # Use Sidekiq if available, otherwise thread-based
         if defined?(::Sidekiq)
-          config.job_backend = :sidekiq
+          config.job.backend = :sidekiq
         else
-          config.job_backend = :thread
+          config.job.backend = :thread
         end
       end
 
@@ -226,7 +223,6 @@ module ::Sinatra
       end
 
       HTM.logger.info "HTM registered with Sinatra application"
-      HTM.logger.debug "HTM job backend: #{HTM.configuration.job_backend}"
     end
   end
 end

data/lib/htm/job_adapter.rb

@@ -14,7 +14,7 @@ class HTM
   #
   # @example Configure job backend
   #   HTM.configure do |config|
-  #     config.job_backend = :active_job
+  #     config.job.backend = :active_job
   #   end
   #
   # @example Enqueue a job
@@ -60,8 +60,6 @@ class HTM
         # Convert job class to ActiveJob if needed
         active_job_class = to_active_job_class(job_class)
         active_job_class.perform_later(**params)
-
-        HTM.logger.debug "Enqueued #{job_class.name} via ActiveJob with params: #{params.inspect}"
       end
 
       # Enqueue job using Sidekiq directly
@@ -76,38 +74,26 @@ class HTM
         # Sidekiq 7.x requires native JSON types - convert symbol keys to strings
         json_params = params.transform_keys(&:to_s)
         sidekiq_class.perform_async(json_params)
-
-        HTM.logger.debug "Enqueued #{job_class.name} via Sidekiq with params: #{params.inspect}"
       end
 
       # Execute job inline (synchronously)
       def enqueue_inline(job_class, **params)
-        HTM.logger.debug "Executing #{job_class.name} inline with params: #{params.inspect}"
-
         begin
           job_class.perform(**params)
-          HTM.logger.debug "Completed #{job_class.name} inline execution"
         rescue StandardError => e
           HTM.logger.error "Inline job #{job_class.name} failed: #{e.class.name} - #{e.message}"
-          HTM.logger.debug e.backtrace.first(5).join("\n")
         end
       end
 
       # Execute job in background thread (legacy)
       def enqueue_thread(job_class, **params)
         Thread.new do
-          HTM.logger.debug "Executing #{job_class.name} in thread with params: #{params.inspect}"
-
           begin
             job_class.perform(**params)
-            HTM.logger.debug "Completed #{job_class.name} thread execution"
           rescue StandardError => e
             HTM.logger.error "Thread job #{job_class.name} failed: #{e.class.name} - #{e.message}"
-            HTM.logger.debug e.backtrace.first(5).join("\n")
           end
         end
-
-        HTM.logger.debug "Started thread for #{job_class.name}"
       rescue StandardError => e
         HTM.logger.error "Failed to start thread for #{job_class.name}: #{e.message}"
       end

data/lib/htm/jobs/generate_embedding_job.rb

@@ -31,17 +31,12 @@ class HTM
         end
 
         # Skip if already has embedding
-        if node.embedding.present?
-          HTM.logger.debug "GenerateEmbeddingJob: Node #{node_id} already has embedding, skipping"
-          return
-        end
+        return if node.embedding.present?
 
         provider = HTM.configuration.embedding_provider.to_s
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         begin
-          HTM.logger.debug "GenerateEmbeddingJob: Generating embedding for node #{node_id}"
-
           # Generate and process embedding using EmbeddingService
           result = HTM::EmbeddingService.generate(node.content)
 
@@ -77,7 +72,6 @@ class HTM
 
           # Log unexpected errors
           HTM.logger.error "GenerateEmbeddingJob: Unexpected error for node #{node_id}: #{e.class.name} - #{e.message}"
-          HTM.logger.debug e.backtrace.first(5).join("\n")
         end
       end
     end

data/lib/htm/jobs/generate_propositions_job.rb

@@ -33,21 +33,12 @@ class HTM
         end
 
         # Skip if this node is already a proposition (prevent recursion)
-        if node.metadata&.dig('is_proposition')
-          HTM.logger.debug "GeneratePropositionsJob: Node #{node_id} is a proposition, skipping"
-          return
-        end
+        return if node.metadata&.dig('is_proposition')
 
         begin
-          HTM.logger.debug "GeneratePropositionsJob: Extracting propositions for node #{node_id}"
-
           # Extract propositions using PropositionService
           propositions = HTM::PropositionService.extract(node.content)
-
-          if propositions.empty?
-            HTM.logger.debug "GeneratePropositionsJob: No propositions extracted for node #{node_id}"
-            return
-          end
+          return if propositions.empty?
 
           HTM.logger.info "GeneratePropositionsJob: Extracted #{propositions.length} propositions for node #{node_id}"
 
@@ -95,7 +86,6 @@ class HTM
         rescue StandardError => e
           # Log unexpected errors
           HTM.logger.error "GeneratePropositionsJob: Unexpected error for node #{node_id}: #{e.class.name} - #{e.message}"
-          HTM.logger.debug e.backtrace.first(5).join("\n")
         end
       end
     end

data/lib/htm/jobs/generate_tags_job.rb

@@ -37,8 +37,6 @@ class HTM
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         begin
-          HTM.logger.debug "GenerateTagsJob: Extracting tags for node #{node_id}"
-
           # Get existing ontology for context (sample of recent tags)
           existing_ontology = HTM::Models::Tag
             .order(created_at: :desc)
@@ -47,11 +45,7 @@ class HTM
 
           # Extract and validate tags using TagService
           tag_names = HTM::TagService.extract(node.content, existing_ontology: existing_ontology)
-
-          if tag_names.empty?
-            HTM.logger.debug "GenerateTagsJob: No tags extracted for node #{node_id}"
-            return
-          end
+          return if tag_names.empty?
 
           # Create or find tags and associate with node
           tag_names.each do |tag_name|
@@ -102,7 +96,6 @@ class HTM
 
           # Log unexpected errors
           HTM.logger.error "GenerateTagsJob: Unexpected error for node #{node_id}: #{e.class.name} - #{e.message}"
-          HTM.logger.debug e.backtrace.first(5).join("\n")
         end
       end
     end

data/lib/htm/loaders/defaults_loader.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'anyway_config'
+require 'yaml'
+
+class HTM
+  module Loaders
+    # Bundled Defaults Loader for Anyway Config
+    #
+    # Loads default configuration values from a YAML file bundled with the gem.
+    # This ensures defaults are always available regardless of where HTM is installed.
+    #
+    # The defaults.yml file has this structure:
+    #   defaults:      # Base values for all environments
+    #     database:
+    #       host: localhost
+    #       port: 5432
+    #   development:   # Overrides for development
+    #     database:
+    #       name: htm_development
+    #   test:          # Overrides for test
+    #     database:
+    #       name: htm_test
+    #   production:    # Overrides for production
+    #     database:
+    #       sslmode: require
+    #
+    # This loader deep-merges `defaults` with the current environment's overrides.
+    #
+    # This loader runs at LOWEST priority (before XDG), so all other sources
+    # can override these bundled defaults:
+    # 1. Bundled defaults (this loader)
+    # 2. XDG user config (~/.config/htm/htm.yml)
+    # 3. Project config (./config/htm.yml)
+    # 4. Local overrides (./config/htm.local.yml)
+    # 5. Environment variables (HTM_*)
+    # 6. Programmatic (configure block)
+    #
+    class DefaultsLoader < Anyway::Loaders::Base
+      DEFAULTS_PATH = File.expand_path('../config/defaults.yml', __dir__).freeze
+
+      class << self
+        # Returns the path to the bundled defaults file
+        #
+        # @return [String] path to defaults.yml
+        def defaults_path
+          DEFAULTS_PATH
+        end
+
+        # Check if defaults file exists
+        #
+        # @return [Boolean]
+        def defaults_exist?
+          File.exist?(DEFAULTS_PATH)
+        end
+
+        # Load and parse the raw YAML content
+        #
+        # @return [Hash] parsed YAML with symbolized keys
+        def load_raw_yaml
+          return {} unless defaults_exist?
+
+          content = File.read(defaults_path)
+          YAML.safe_load(
+            content,
+            permitted_classes: [Symbol],
+            symbolize_names: true,
+            aliases: true
+          ) || {}
+        rescue Psych::SyntaxError => e
+          warn "HTM: Failed to parse bundled defaults #{defaults_path}: #{e.message}"
+          {}
+        end
+
+        # Extract the schema (attribute names) from the defaults section
+        #
+        # @return [Hash] the defaults section containing all attribute definitions
+        def schema
+          raw = load_raw_yaml
+          raw[:defaults] || {}
+        end
+      end
+
+      def call(name:, **_options)
+        return {} unless self.class.defaults_exist?
+
+        trace!(:bundled_defaults, path: self.class.defaults_path) do
+          load_and_merge_for_environment
+        end
+      end
+
+      private
+
+      # Load defaults and deep merge with environment-specific overrides
+      #
+      # @return [Hash] merged configuration for current environment
+      def load_and_merge_for_environment
+        raw = self.class.load_raw_yaml
+        return {} if raw.empty?
+
+        # Start with the defaults section
+        defaults = raw[:defaults] || {}
+
+        # Deep merge with environment-specific overrides
+        env = current_environment
+        env_overrides = raw[env.to_sym] || {}
+
+        deep_merge(defaults, env_overrides)
+      end
+
+      # Deep merge two hashes, with overlay taking precedence
+      #
+      # @param base [Hash] base configuration
+      # @param overlay [Hash] overlay configuration (takes precedence)
+      # @return [Hash] merged result
+      def deep_merge(base, overlay)
+        base.merge(overlay) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      # Determine the current environment
+      #
+      # Priority: HTM_ENV > RAILS_ENV > RACK_ENV > 'development'
+      #
+      # @return [String] current environment name
+      def current_environment
+        ENV['HTM_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+      end
+    end
+  end
+end
+
+# Register the defaults loader at LOWEST priority (before :yml loader)
+# This ensures bundled defaults are overridden by all other sources:
+# - XDG user config (registered after this, also before :yml)
+# - Project config (:yml loader)
+# - Environment variables (:env loader)
+Anyway.loaders.insert_before :yml, :bundled_defaults, HTM::Loaders::DefaultsLoader

data/lib/htm/loaders/xdg_config_loader.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'anyway_config'
+require 'yaml'
+
+class HTM
+  module Loaders
+    # XDG Base Directory Specification loader for Anyway Config
+    #
+    # Loads configuration from XDG-compliant paths:
+    # 1. $XDG_CONFIG_HOME/htm/htm.yml (if XDG_CONFIG_HOME is set)
+    # 2. ~/.config/htm/htm.yml (XDG default fallback)
+    #
+    # On macOS, also checks:
+    # 3. ~/Library/Application Support/htm/htm.yml
+    #
+    # This loader runs BEFORE the project-local config loader,
+    # so project configs take precedence over user-global configs.
+    #
+    # @example XDG config file location
+    #   ~/.config/htm/htm.yml
+    #
+    # @example Custom XDG_CONFIG_HOME
+    #   export XDG_CONFIG_HOME=/my/config
+    #   # Looks for /my/config/htm/htm.yml
+    #
+    class XdgConfigLoader < Anyway::Loaders::Base
+      class << self
+        # Returns all XDG config paths to check, in order of priority (lowest first)
+        #
+        # @return [Array<String>] list of potential config file paths
+        def config_paths
+          paths = []
+
+          # macOS Application Support (lowest priority for XDG loader)
+          if macos?
+            macos_path = File.expand_path('~/Library/Application Support/htm')
+            paths << macos_path if Dir.exist?(File.dirname(macos_path))
+          end
+
+          # XDG default: ~/.config/htm
+          xdg_default = File.expand_path('~/.config/htm')
+          paths << xdg_default
+
+          # XDG_CONFIG_HOME override (highest priority for XDG loader)
+          if ENV['XDG_CONFIG_HOME'] && !ENV['XDG_CONFIG_HOME'].empty?
+            xdg_home = File.join(ENV['XDG_CONFIG_HOME'], 'htm')
+            paths << xdg_home unless xdg_home == xdg_default
+          end
+
+          paths
+        end
+
+        # Find the first existing config file
+        #
+        # @param name [String] config name (e.g., 'htm')
+        # @return [String, nil] path to config file or nil if not found
+        def find_config_file(name)
+          config_paths.reverse_each do |dir|
+            file = File.join(dir, "#{name}.yml")
+            return file if File.exist?(file)
+          end
+          nil
+        end
+
+        private
+
+        def macos?
+          RUBY_PLATFORM.include?('darwin')
+        end
+      end
+
+      def call(name:, **_options)
+        config_file = self.class.find_config_file(name)
+        return {} unless config_file
+
+        trace!(:xdg, path: config_file) do
+          load_yaml(config_file, name)
+        end
+      end
+
+      private
+
+      def load_yaml(path, name)
+        return {} unless File.exist?(path)
+
+        content = File.read(path)
+        parsed = YAML.safe_load(content, permitted_classes: [Symbol], symbolize_names: true, aliases: true) || {}
+
+        # Support environment-specific configs
+        env = Anyway::Settings.current_environment ||
+              ENV['HTM_ENV'] ||
+              ENV['RAILS_ENV'] ||
+              ENV['RACK_ENV'] ||
+              'development'
+
+        # Check for environment key first, fall back to root level
+        if parsed.key?(env.to_sym)
+          parsed[env.to_sym] || {}
+        elsif parsed.key?(env.to_s)
+          parsed[env.to_s] || {}
+        else
+          # No environment key, treat as flat config
+          parsed
+        end
+      rescue Psych::SyntaxError => e
+        warn "HTM: Failed to parse XDG config #{path}: #{e.message}"
+        {}
+      end
+    end
+  end
+end
+
+# Register the XDG loader with Anyway Config
+# Insert before :yml so project-local config takes precedence
+Anyway.loaders.insert_before :yml, :xdg, HTM::Loaders::XdgConfigLoader