legion-settings 1.3.26 → 1.3.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d1e8b1f3f0f96ee8db9d11604d914fc253e430827e37f7e30cc244151dc75b
-  data.tar.gz: 1ed13e9f16b97fc33acc72e484671794210ac4750aef5502fc86e685ec2f9324
+  metadata.gz: 6a096c46e4b074a4e77c104f21b1dc89b953ad15370e514ccd7face8cf8a7b8f
+  data.tar.gz: 06475bdc9bf41c6219e2c61fef17006346bb57b833a9a6c992a02f1d1178047a
 SHA512:
-  metadata.gz: 47ab18a67eef8c35d86e52e9deec5716916754e5a84e0faec1ba3bbed4f24e9f4bb5c7749268eee23c96056ce85ef11c47787ac2df06fa5b918365730ddf6926
-  data.tar.gz: c76877c9e9a19f44c33a816a0580c265f721fe6dd0ef486eb06ec377ac6aedd5ae60fe52b4aaf4d8feb59bb18527f6127da40a0611d27718de3be63af5581b97
+  metadata.gz: 30cc986020bd6c2f4c783193f65fb07b935e08ddadd1a00608a90001a8312da19e88612e99449bc283ae4d716d119f22517c37809670f50e854a8658502c645f
+  data.tar.gz: 7d41547be02a86b3afc065e8865dbe16c02ebde7b592bd7f9a83585b22d7f07cfc1fe078eb171b754f2398d9fce9942410e8b9b999e744a73ee6abf378ada1bb

data/.gitignore

@@ -9,7 +9,8 @@
 /tmp/
 /legion/.idea/
 /.idea/
+*.gem
 *.key
 # rspec failure tracking
 .rspec_status
-legionio.key
+legionio.key

data/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# Standard LegionIO pre-commit configuration
+# Install: pre-commit install
+# Manual:  pre-commit run --all-files
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+        exclude: Gemfile\.lock
+      - id: check-merge-conflict
+
+  - repo: local
+    hooks:
+      - id: rubocop
+        name: RuboCop (autofix)
+        entry: scripts/pre-commit-rubocop.sh
+        language: script
+        types: [ruby]
+        pass_filenames: true
+
+      - id: ruby-syntax
+        name: Ruby syntax check
+        entry: ruby -c
+        language: system
+        types: [ruby]
+        pass_filenames: true

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Legion::Settings Changelog
 
+## [1.3.27] - 2026-04-27
+
+### Added
+- `Settings.reload!` — re-reads all previously loaded config files and re-resolves vault://, env://, and lease:// references; returns a hash of changed keys with old/new values; thread-safe via internal mutex
+- `Settings.watch!` — registers a SIGHUP handler that triggers `reload!` in a background thread; optionally accepts a block for change notification
+- `Settings.on_reload(&block)` — register callbacks invoked after `reload!` detects changes; multiple callbacks supported, called in order, rescue-safe
+- Private `diff_settings` helper for deep comparison of old vs new config hashes
+- Private `fire_reload_callbacks` for executing registered change callbacks
+
+### Fixed
+- `reload!` preserves programmatic module merges and reapplies `.legionio.env` overrides to the reloaded settings loader
+- `watch!` no-ops when SIGHUP is unavailable and coalesces repeated SIGHUP events through a single reload worker
+- Replaced deprecated helper logging method calls with direct `log.debug/info/warn/error` usage
+
 ## [1.3.26] - 2026-04-02
 
 ### Changed

data/README.md

@@ -2,7 +2,7 @@
 
 Configuration management module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Loads settings from JSON files, directories, and environment variables. Provides a unified `Legion::Settings[:key]` accessor used by all other Legion gems.
 
-**Version**: 1.3.26
+**Version**: 1.3.27
 
 ## Installation
 
@@ -44,6 +44,51 @@ If a caller wants the canonical Legion search directories, use `Legion::Settings
 
 Each Legion module registers its own defaults via `merge_settings` during startup, and the nearest `.legionio.env` file is merged on top of base settings. Request overlays applied through `with_overlay` take highest precedence.
 
+### Hot Reload
+
+`Legion::Settings.reload!` re-reads the config files that were previously loaded, reapplies module defaults and the nearest `.legionio.env`, re-resolves secret references, and returns a hash describing the changed keys.
+
+```ruby
+changes = Legion::Settings.reload!
+
+changes
+# {
+#   "llm.default_model" => { old: "old-model", new: "new-model" }
+# }
+```
+
+Callbacks run only when changes are detected:
+
+```ruby
+Legion::Settings.on_reload do |changes|
+  Legion::Settings.logger.info("Settings changed: #{changes.keys.join(', ')}")
+end
+```
+
+`watch!` installs a SIGHUP handler when the platform supports it. Repeated signals are coalesced through one background reload worker, so rapid SIGHUP bursts do not create unbounded reload threads.
+
+```ruby
+Legion::Settings.watch! do |changes|
+  Legion::Settings.logger.info("Reloaded #{changes.size} setting(s)")
+end
+
+# Later, from a shell:
+# kill -HUP <daemon_pid>
+```
+
+On platforms without `HUP`, `watch!` logs and returns without raising. Direct `reload!` remains available for API endpoints, tests, or environments that use a different process-control mechanism.
+
+### Project Environment Overrides
+
+When present, the nearest `.legionio.env` file is loaded after base settings and module defaults. Dot notation maps to nested settings:
+
+```dotenv
+llm.default_model=claude-sonnet
+cache.driver=redis
+```
+
+Hot reload picks up changes to this file as part of the same `reload!` flow.
+
 ### Secret Resolution
 
 Settings values can reference external secret sources using URI syntax. Three schemes are supported:

data/lib/legion/settings/agent_loader.rb

@@ -20,7 +20,7 @@ module Legion
             definition = load_file(path)
             next unless definition && valid?(definition)
 
-            log_debug("Agent loaded: #{definition[:name]} (#{path})")
+            log.debug("Agent loaded: #{definition[:name]} (#{path})")
             definition.merge(_source_path: path, _source_mtime: File.mtime(path))
           end
         end
@@ -32,7 +32,7 @@ module Legion
           when '.json'         then ::JSON.parse(content, symbolize_names: true)
           end
         rescue StandardError => e
-          log_warn("Failed to parse agent file #{path}: #{e.message}")
+          log.warn("Failed to parse agent file #{path}: #{e.message}")
           nil
         end
 
@@ -51,14 +51,6 @@ module Legion
           raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
           raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
         end
-
-        def log_debug(message)
-          log.debug(message)
-        end
-
-        def log_warn(message)
-          log.warn(message)
-        end
       end
     end
   end

data/lib/legion/settings/loader.rb

@@ -15,7 +15,7 @@ module Legion
       include Legion::Logging::Helper
 
       class Error < RuntimeError; end
-      attr_reader :warnings, :errors, :loaded_files, :settings
+      attr_reader :warnings, :errors, :loaded_files, :settings, :merged_modules
 
       def self.default_directories
         env_dirs = ENV.fetch('LEGION_SETTINGS_DIRS', nil)
@@ -40,6 +40,7 @@ module Legion
         @settings = default_settings
         @indifferent_access = false
         @loaded_files = []
+        @merged_modules = {}
         log.debug('Initialized Legion::Settings::Loader with default settings')
       end
 
@@ -221,20 +222,21 @@ module Legion
 
       def load_module_settings(config)
         mod_name = config.keys.first
-        log_debug("Loading module settings: #{mod_name}")
+        log.debug("Loading module settings: #{mod_name}")
+        @merged_modules = deep_merge(@merged_modules, config)
         @settings = deep_merge(config, @settings)
         mark_dirty!
       end
 
       def load_module_default(config)
         mod_name = config.keys.first
-        log_debug("Loading module defaults: #{mod_name}")
+        log.debug("Loading module defaults: #{mod_name}")
         @settings = deep_merge(config, @settings)
         mark_dirty!
       end
 
       def load_file(file)
-        log_debug("Trying to load file #{file}")
+        log.debug("Trying to load file #{file}")
         if File.file?(file) && File.readable?(file)
           begin
             contents = read_config_file(file)
@@ -244,11 +246,11 @@ module Legion
             @loaded_files << file
             log.debug("Loaded settings file #{file}")
           rescue Legion::JSON::ParseError => e
-            log_error("config file must be valid json: #{file}")
-            log_error("  parse error: #{e.message}")
+            log.error("config file must be valid json: #{file}")
+            log.error("  parse error: #{e.message}")
           end
         else
-          log_warn("Config file does not exist or is not readable file:#{file}")
+          log.warn("Config file does not exist or is not readable file:#{file}")
         end
       end
 
@@ -257,7 +259,7 @@ module Legion
         if File.readable?(path) && File.executable?(path)
           files = Dir.glob(File.join(path, '**', '*.json'))
           files.each { |file| load_file(file) }
-          log_info("Settings: loaded directory #{path} (#{files.size} files)")
+          log.info("Settings: loaded directory #{path} (#{files.size} files)")
         else
           load_error('insufficient permissions for loading', directory: directory)
         end
@@ -270,7 +272,7 @@ module Legion
           @settings[:client][:subscriptions].uniq!
           mark_dirty!
         else
-          log_warn('unable to apply legion client overrides, reason: client subscriptions is not an array')
+          log.warn('unable to apply legion client overrides, reason: client subscriptions is not an array')
         end
       end
 
@@ -302,7 +304,7 @@ module Legion
       end
 
       def load_dns_first_boot(bootstrap)
-        log_debug("DNS bootstrap: first boot, fetching from #{bootstrap.url}")
+        log.debug("DNS bootstrap: first boot, fetching from #{bootstrap.url}")
         config = bootstrap.fetch
         bootstrap.write_cache(config) if config
         config
@@ -324,7 +326,7 @@ module Legion
           fresh = bootstrap.fetch
           bootstrap.write_cache(fresh) if fresh
         rescue StandardError => e
-          log_warn("DNS background refresh failed: #{e.message}")
+          log.warn("DNS background refresh failed: #{e.message}")
         end
       end
 
@@ -361,7 +363,7 @@ module Legion
 
         @settings[:api] ||= {}
         @settings[:api][:port] = ENV['LEGION_API_PORT'].to_i
-        log_warn("using api port environment variable, api: #{@settings[:api]}")
+        log.warn("using api port environment variable, api: #{@settings[:api]}")
         mark_dirty!
       end
 
@@ -423,7 +425,7 @@ module Legion
       def system_hostname
         Socket.gethostname
       rescue StandardError => e
-        log_debug("Legion::Settings::Loader#system_hostname failed: #{e.message}")
+        log.debug("Legion::Settings::Loader#system_hostname failed: #{e.message}")
         'unknown'
       end
 
@@ -432,7 +434,7 @@ module Legion
         preferred = addresses.find { |a| rfc1918?(a.ip_address) }
         (preferred || addresses.first)&.ip_address || 'unknown'
       rescue StandardError => e
-        log_debug("Legion::Settings::Loader#system_address failed: #{e.message}")
+        log.debug("Legion::Settings::Loader#system_address failed: #{e.message}")
         'unknown'
       end
 
@@ -442,34 +444,18 @@ module Legion
           ip.start_with?('192.168.')
       end
 
-      def log_info(message)
-        log.info(message)
-      end
-
-      def log_debug(message)
-        log.debug(message)
-      end
-
-      def log_warn(message)
-        log.warn(message)
-      end
-
-      def log_error(message)
-        log.error(message)
-      end
-
       def warning(message, data = {})
         @warnings << {
           message: message
         }.merge(data)
-        log_warn(message)
+        log.warn(message)
       end
 
       def load_error(message, data = {})
         @errors << {
           message: message
         }.merge(data)
-        log_error(message)
+        log.error(message)
         raise(Error, message)
       end
 
@@ -480,7 +466,7 @@ module Legion
           nameservers:    config[:nameserver]&.map(&:to_s)&.uniq
         }
       rescue StandardError => e
-        log_warn("Failed to read resolv config: #{e.message}")
+        log.warn("Failed to read resolv config: #{e.message}")
         { search_domains: [], nameservers: [] }
       end
 
@@ -491,10 +477,10 @@ module Legion
 
         fqdn.include?('.') ? fqdn : nil
       rescue Timeout::Error
-        log_debug('FQDN detection skipped (DNS timeout)')
+        log.debug('FQDN detection skipped (DNS timeout)')
         nil
       rescue StandardError => e
-        log_debug("FQDN detection skipped (#{e.message.split(':').first})")
+        log.debug("FQDN detection skipped (#{e.message.split(':').first})")
         nil
       end
     end

data/lib/legion/settings/project_env.rb

@@ -57,14 +57,14 @@ module Legion
 
             parts = line.split('=', 2)
             unless parts.length == 2
-              log_warn("#{path}:#{idx + 1}: skipping malformed line (no '=' found)")
+              log.warn("#{path}:#{idx + 1}: skipping malformed line (no '=' found)")
               next
             end
 
             raw_key, value = parts
             key_parts = raw_key.strip.split('.')
             if key_parts.empty? || key_parts.any?(&:empty?)
-              log_warn("#{path}:#{idx + 1}: skipping invalid key '#{raw_key.strip}'")
+              log.warn("#{path}:#{idx + 1}: skipping invalid key '#{raw_key.strip}'")
               next
             end
 
@@ -85,7 +85,7 @@ module Legion
 
           overrides = parse_env_file(path)
           deep_merge_into!(settings, overrides)
-          log_debug("ProjectEnv: loaded #{path}")
+          log.debug("ProjectEnv: loaded #{path}")
           path
         end
 
@@ -115,14 +115,6 @@ module Legion
           end
           base
         end
-
-        def log_debug(message)
-          log.debug(message)
-        end
-
-        def log_warn(message)
-          log.warn(message)
-        end
       end
     end
   end

data/lib/legion/settings/resolver.rb

@@ -21,10 +21,10 @@ module Legion
         @vault_cache     = {}
 
         vault_count = count_vault_refs(settings_hash)
-        log_warn("Vault not connected — #{vault_count} vault:// reference(s) will not be resolved") if vault_count.positive? && !@vault_available
+        log.warn("Vault not connected — #{vault_count} vault:// reference(s) will not be resolved") if vault_count.positive? && !@vault_available
 
         lease_count = count_lease_refs(settings_hash)
-        log_warn("LeaseManager not available — #{lease_count} lease:// reference(s) will not be resolved") if lease_count.positive? && !lease_manager_available?
+        log.warn("LeaseManager not available — #{lease_count} lease:// reference(s) will not be resolved") if lease_count.positive? && !lease_manager_available?
 
         resolved = 0
         unresolved = 0
@@ -36,7 +36,7 @@ module Legion
           end
         end
 
-        log_info("Settings resolver: #{resolved} resolved, #{unresolved} unresolved") if resolved.positive? || unresolved.positive?
+        log.info("Settings resolver: #{resolved} resolved, #{unresolved} unresolved") if resolved.positive? || unresolved.positive?
 
         settings_hash
       end
@@ -101,7 +101,7 @@ module Legion
         Legion::Settings[:crypt][:vault][:connected] == true ||
           (Legion::Crypt.respond_to?(:connected_clusters) && Legion::Crypt.connected_clusters.any?)
       rescue StandardError => e
-        log_debug("Legion::Settings::Resolver#vault_connected? failed: #{e.message}")
+        log.debug("Legion::Settings::Resolver#vault_connected? failed: #{e.message}")
         false
       end
 
@@ -136,7 +136,7 @@ module Legion
 
         resolved = resolve_single(value)
         if resolved.nil?
-          log_warn("Settings resolver: could not resolve #{current_path} (#{value})")
+          log.warn("Settings resolver: could not resolve #{current_path} (#{value})")
           yield(:unresolved) if block_given?
         else
           container[key] = resolved
@@ -149,7 +149,7 @@ module Legion
         if resolvable_chain?(value) && value.all? { |entry| !entry.is_a?(Hash) && !entry.is_a?(Array) }
           resolved = resolve_chain(value)
           if resolved.nil?
-            log_warn("Settings resolver: fallback chain exhausted for #{current_path}")
+            log.warn("Settings resolver: fallback chain exhausted for #{current_path}")
             yield(:unresolved) if block_given?
           else
             container[key] = resolved
@@ -162,27 +162,27 @@ module Legion
       end
 
       def resolve_vault(path, key)
-        log_debug("resolve_vault: path=#{path}, key=#{key}, vault_available=#{@vault_available}")
+        log.debug("resolve_vault: path=#{path}, key=#{key}, vault_available=#{@vault_available}")
         return nil unless @vault_available
 
         @vault_cache[path] ||= begin
-          log_debug("resolve_vault: calling Legion::Crypt.read(#{path.inspect})")
+          log.debug("resolve_vault: calling Legion::Crypt.read(#{path.inspect})")
           result = Legion::Crypt.read(path)
-          log_debug("resolve_vault: read returned #{result.nil? ? 'nil' : "keys=#{result.keys.inspect}"}")
+          log.debug("resolve_vault: read returned #{result.nil? ? 'nil' : "keys=#{result.keys.inspect}"}")
           result
         rescue StandardError => e
-          log_warn("Settings resolver: vault read failed for #{path}: #{e.class}=#{e.message}")
+          log.warn("Settings resolver: vault read failed for #{path}: #{e.class}=#{e.message}")
           nil
         end
 
         data = @vault_cache[path]
         unless data.is_a?(Hash)
-          log_debug("resolve_vault: data at #{path} is #{data.class}, returning nil")
+          log.debug("resolve_vault: data at #{path} is #{data.class}, returning nil")
           return nil
         end
 
         value = data[key.to_sym] || data[key.to_s]
-        log_debug("resolve_vault: #{path}##{key} = #{value.nil? ? 'nil' : '<present>'}")
+        log.debug("resolve_vault: #{path}##{key} = #{value.nil? ? 'nil' : '<present>'}")
         value
       end
 
@@ -191,14 +191,14 @@ module Legion
 
         Legion::Crypt::LeaseManager.instance.fetch(name, key)
       rescue StandardError => e
-        log_debug("Settings resolver: lease fetch failed for #{name}##{key}: #{e.message}")
+        log.debug("Settings resolver: lease fetch failed for #{name}##{key}: #{e.message}")
         nil
       end
 
       def lease_manager_available?
         defined?(Legion::Crypt::LeaseManager)
       rescue StandardError => e
-        log_debug("Legion::Settings::Resolver#lease_manager_available? failed: #{e.message}")
+        log.debug("Legion::Settings::Resolver#lease_manager_available? failed: #{e.message}")
         false
       end
 
@@ -215,7 +215,7 @@ module Legion
         path_parts = path_string.split('.').map(&:to_sym)
         Legion::Crypt::LeaseManager.instance.register_ref(m[1], m[2], path_parts)
       rescue StandardError => e
-        log_debug("Legion::Settings::Resolver#register_lease_ref failed for #{path_string}: #{e.message}")
+        log.debug("Legion::Settings::Resolver#register_lease_ref failed for #{path_string}: #{e.message}")
         nil
       end
 
@@ -242,18 +242,6 @@ module Legion
         raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
         raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
       end
-
-      def log_info(message)
-        log.info(message)
-      end
-
-      def log_warn(message)
-        log.warn(message)
-      end
-
-      def log_debug(message)
-        log.debug(message)
-      end
     end
   end
 end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.3.26'
+    VERSION = '1.3.27'
   end
 end

data/lib/legion/settings.rb

@@ -125,10 +125,10 @@ module Legion
       #
       # @param start_dir [String, nil] directory to start searching from (defaults to Dir.pwd)
       # @return [String, nil] path to the loaded file, or nil if none found
-      def load_project_env(start_dir: nil)
-        ensure_loader
-        path = ProjectEnv.load_into(@loader.settings, start_dir: start_dir)
-        @loader.mark_dirty! if path
+      def load_project_env(start_dir: nil, loader: nil)
+        target_loader = loader || ensure_loader
+        path = ProjectEnv.load_into(target_loader.settings, start_dir: start_dir)
+        target_loader.mark_dirty! if path
         path
       end
 
@@ -184,11 +184,118 @@ module Legion
         @loader.errors
       end
 
+      # ------------------------------------------------------------------
+      # Hot-reload: re-read all previously loaded config files, re-resolve
+      # vault:// / env:// / lease:// references, and notify registered
+      # callbacks of changed keys.
+      #
+      # Safe to call from a SIGHUP handler or API endpoint.
+      #
+      # @return [Hash] changed keys  { key => { old: ..., new: ... } }
+      # ------------------------------------------------------------------
+      def reload!
+        @reload_mutex ||= Mutex.new
+        @reload_mutex.synchronize do
+          return {} unless @loader
+
+          old_hash = @loader.to_hash.dup
+          files = @loader.loaded_files.dup
+
+          # Re-create loader and replay the same files
+          new_loader = Legion::Settings::Loader.new
+          new_loader.load_env
+          new_loader.load_dns_bootstrap
+          files.each { |f| new_loader.load_file(f) if File.exist?(f) }
+
+          # Replay module merges so extension defaults are preserved
+          if @loader.respond_to?(:merged_modules)
+            @loader.merged_modules.each do |mod_key, mod_defaults|
+              new_loader.load_module_settings(mod_key => mod_defaults)
+            end
+          end
+
+          # Replay project env overrides (.legionio.env)
+          load_project_env(loader: new_loader)
+
+          # Re-resolve secrets (vault://, env://, lease://)
+          begin
+            require 'legion/settings/resolver'
+            Resolver.resolve_secrets!(new_loader.to_hash)
+          rescue StandardError => e
+            logger.warn("Settings reload: secret resolution failed: #{e.message}")
+          end
+
+          new_hash = new_loader.to_hash
+          changes = diff_settings(old_hash, new_hash)
+
+          if changes.empty?
+            logger.info('Settings reload: no changes detected')
+          else
+            @loader = new_loader
+            logger.info("Settings reload: #{changes.size} key(s) changed — #{changes.keys.join(', ')}")
+            fire_reload_callbacks(changes)
+          end
+
+          changes
+        end
+      end
+
+      # Register a SIGHUP handler that triggers reload!
+      # Optionally accepts a block that will be called with the changes hash
+      # after each successful reload.
+      #
+      # @yield [changes] optional callback receiving the changes hash
+      def watch!(&block)
+        on_reload(&block) if block
+
+        unless Signal.list.key?('HUP')
+          logger.info('Settings: SIGHUP not available on this platform — watch! is a no-op')
+          return
+        end
+
+        # Single coalescing worker thread: SIGHUP sets the flag, worker drains it.
+        @reload_flag ||= Queue.new
+        @reload_worker ||= Thread.new do
+          loop do
+            @reload_flag.pop # blocks until signalled
+            # Drain any queued signals so rapid SIGHUPs collapse into one reload
+            @reload_flag.pop until @reload_flag.empty?
+            logger.info('Settings: SIGHUP received — reloading configuration')
+            reload!
+          rescue StandardError => e
+            logger.error("Settings: reload after SIGHUP failed: #{e.message}")
+          end
+        end
+
+        trap('HUP') { @reload_flag << :reload }
+        logger.info('Settings: SIGHUP handler registered for config hot-reload')
+      end
+
+      # Register a callback to be invoked after reload! detects changes.
+      # Multiple callbacks can be registered; they are called in order.
+      #
+      # @yield [changes] the changes hash { key => { old: ..., new: ... } }
+      def on_reload(&block)
+        raise ArgumentError, 'on_reload requires a block' unless block
+
+        @reload_callbacks ||= []
+        @reload_callbacks << block
+      end
+
       def reset!
+        if @reload_worker&.alive? && @reload_worker != Thread.current
+          @reload_worker.kill
+          @reload_worker.join
+        end
+
         @loader = nil
         @loaded = nil
         @schema = nil
         @cross_validations = nil
+        @reload_callbacks = nil
+        @reload_mutex = nil
+        @reload_flag = nil
+        @reload_worker = nil
         Overlay.clear_overlay!
       end
 
@@ -274,6 +381,32 @@ module Legion
           @loader.errors << w
         end
       end
+
+      def diff_settings(old_hash, new_hash, prefix = '')
+        changes = {}
+        all_keys = (old_hash.keys + new_hash.keys).uniq
+        all_keys.each do |key|
+          full_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+          old_val = old_hash[key]
+          new_val = new_hash[key]
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            changes.merge!(diff_settings(old_val, new_val, full_key))
+          elsif old_val != new_val
+            changes[full_key] = { old: old_val, new: new_val }
+          end
+        end
+        changes
+      end
+
+      def fire_reload_callbacks(changes)
+        return unless @reload_callbacks&.any?
+
+        @reload_callbacks.each do |cb|
+          cb.call(changes)
+        rescue StandardError => e
+          logger.warn("Settings reload callback failed: #{e.message}")
+        end
+      end
     end
   end
 end

data/scripts/pre-commit-rubocop.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Pre-commit hook: run RuboCop with autofix on staged Ruby files.
+# Tries rubocop directly, then bundle exec. If the binary is truly
+# unavailable (exit 127 / crash / Prism conflict), warns and defers
+# to CI. If rubocop runs but reports offenses, fails the commit.
+set -uo pipefail
+
+run_rubocop() {
+  output=$("$@" -A --force-exclusion "${FILES[@]}" 2>&1)
+  rc=$?
+  if [ $rc -eq 0 ] || [ $rc -eq 1 ]; then
+    # rubocop ran successfully: 0 = clean, 1 = offenses found
+    echo "$output"
+    return $rc
+  fi
+  # exit > 1 means rubocop crashed / couldn't load
+  return 2
+}
+
+FILES=("$@")
+
+if run_rubocop rubocop; then
+  exit 0
+elif [ $? -eq 1 ]; then
+  echo "RuboCop found offenses that could not be auto-corrected."
+  exit 1
+fi
+
+if run_rubocop bundle exec rubocop; then
+  exit 0
+elif [ $? -eq 1 ]; then
+  echo "RuboCop found offenses that could not be auto-corrected."
+  exit 1
+fi
+
+echo "⚠  RuboCop not available locally (Prism conflict?) — CI will enforce."
+echo "   Run 'ruby -c' to at least verify syntax."
+ruby -c "$@" 2>&1 || exit 1
+exit 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.3.26
+  version: 1.3.27
 platform: ruby
 authors:
 - Esity
@@ -52,6 +52,7 @@ files:
 - ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
+- ".pre-commit-config.yaml"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CLAUDE.md
@@ -75,6 +76,7 @@ files:
 - lib/legion/settings/validation_error.rb
 - lib/legion/settings/validators/tls.rb
 - lib/legion/settings/version.rb
+- scripts/pre-commit-rubocop.sh
 - sonar-project.properties
 homepage: https://github.com/LegionIO/legion-settings
 licenses: