ultra_settings 2.8.1 → 2.9.1

data/lib/ultra_settings.rb

@@ -8,24 +8,6 @@ require "singleton"
 require "digest"
 require "uri"
 
-require_relative "ultra_settings/configuration"
-require_relative "ultra_settings/coerce"
-require_relative "ultra_settings/config_helper"
-require_relative "ultra_settings/field"
-require_relative "ultra_settings/rack_app"
-require_relative "ultra_settings/view_helper"
-require_relative "ultra_settings/render_helper"
-require_relative "ultra_settings/web_view"
-require_relative "ultra_settings/application_view"
-require_relative "ultra_settings/configuration_view"
-require_relative "ultra_settings/uninitialized_runtime_settings"
-require_relative "ultra_settings/yaml_config"
-require_relative "ultra_settings/version"
-
-if defined?(Rails::Railtie)
-  require_relative "ultra_settings/railtie"
-end
-
 # This is the root namespace for UltraSettings. You can add configurations to
 # this namespace using the add method.
 #
@@ -33,13 +15,29 @@ end
 #   UltraSettings.add(:test)
 #   UltraSettings.test # => TestConfiguration.instance
 module UltraSettings
-  VALID_NAME__PATTERN = /\A[a-z_][a-zA-Z0-9_]*\z/
+  autoload :Configuration, File.join(__dir__, "ultra_settings/configuration")
+  autoload :Coerce, File.join(__dir__, "ultra_settings/coerce")
+  autoload :ConfigHelper, File.join(__dir__, "ultra_settings/config_helper")
+  autoload :Field, File.join(__dir__, "ultra_settings/field")
+  autoload :MiniI18n, File.join(__dir__, "ultra_settings/mini_i18n")
+  autoload :RackApp, File.join(__dir__, "ultra_settings/rack_app")
+  autoload :ViewHelper, File.join(__dir__, "ultra_settings/view_helper")
+  autoload :RenderHelper, File.join(__dir__, "ultra_settings/render_helper")
+  autoload :WebView, File.join(__dir__, "ultra_settings/web_view")
+  autoload :ApplicationView, File.join(__dir__, "ultra_settings/application_view")
+  autoload :ConfigurationView, File.join(__dir__, "ultra_settings/configuration_view")
+  autoload :UninitializedRuntimeSettings, File.join(__dir__, "ultra_settings/uninitialized_runtime_settings")
+  autoload :YamlConfig, File.join(__dir__, "ultra_settings/yaml_config")
+  autoload :VERSION, File.join(__dir__, "ultra_settings/version")
+
+  VALID_NAME_PATTERN = /\A[a-z_][a-zA-Z0-9_]*\z/
 
   @configurations = {}
   @mutex = Mutex.new
   @runtime_settings = nil
   @runtime_settings_url = nil
   @runtime_settings_secure = true
+  @super_settings_api_path = nil
 
   class << self
     # Adds a configuration to the root namespace. The configuration will be
@@ -52,7 +50,7 @@ module UltraSettings
     # @return [void]
     def add(name, klass = nil)
       name = name.to_s
-      unless name.match?(VALID_NAME__PATTERN)
+      unless name.match?(VALID_NAME_PATTERN)
         raise ArgumentError.new("Invalid configuration name: #{name.inspect}")
       end
 
@@ -219,6 +217,38 @@ module UltraSettings
       @runtime_settings_secure
     end
 
+    # Set the URL path where the SuperSettings API is mounted. When this is set,
+    # the web UI will check the SuperSettings API at this path for edit access
+    # and load the SuperSettings api.js client library to enable inline editing
+    # of runtime settings.
+    #
+    # The path must be a relative URL path starting with "/". Authorization is
+    # handled entirely by SuperSettings — the browser makes a GET request to
+    # the /authorized endpoint to check access and all API calls go directly
+    # to the SuperSettings endpoint.
+    #
+    # @param value [String, nil] The relative URL path where SuperSettings is mounted.
+    # @return [void]
+    def super_settings_api_path=(value)
+      raise "super_settings gem is required for super_settings_api_path" unless defined?(::SuperSettings)
+
+      if value.nil?
+        @super_settings_api_path = nil
+        return
+      end
+
+      value = value.to_s
+      raise ArgumentError, "super_settings_api_path must be a relative URL path starting with '/'" unless value.start_with?("/")
+
+      @super_settings_api_path = value.chomp("/")
+      self.runtime_settings = ::SuperSettings
+    end
+
+    # Get the URL path where the SuperSettings API is mounted.
+    #
+    # @return [String, nil]
+    attr_reader :super_settings_api_path
+
     # Set whether fields should be considered secret by default.
     #
     # @param value [Boolean] Whether fields should be secret by default.
@@ -304,14 +334,18 @@ module UltraSettings
       if name.respond_to?(:classify)
         name.classify
       else
-        name.split("_").map(&:capitalize).join.gsub("/", "::")
+        name.to_s.split("_").map(&:capitalize).join.gsub("/", "::")
       end
     end
 
     def constantize(class_name)
-      class_name.split("::").reduce(Object) do |mod, name|
+      class_name.to_s.split("::").reduce(Object) do |mod, name|
         mod.const_get(name)
       end
     end
   end
 end
+
+if defined?(Rails::Railtie)
+  require_relative "ultra_settings/railtie"
+end

data/ultra_settings.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   ignore_files = %w[
     .
+    AGENTS.md
     Appraisals
     Gemfile
     Gemfile.lock

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.9.1
 platform: ruby
 authors:
 - Brian Durand
@@ -29,16 +29,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE.txt
 - README.md
 - VERSION
+- app/AGENTS.md
 - app/_config_description.html.erb
 - app/_config_list.html.erb
 - app/_data_source.html.erb
-- app/_select_menu.html.erb
 - app/application.css
 - app/application.js
 - app/application_vars.css.erb
@@ -47,6 +46,36 @@ files:
 - app/layout.css
 - app/layout.html.erb
 - app/layout_vars.css.erb
+- app/locales/ar.json
+- app/locales/cs.json
+- app/locales/da.json
+- app/locales/de.json
+- app/locales/el.json
+- app/locales/en.json
+- app/locales/es.json
+- app/locales/fa.json
+- app/locales/fr.json
+- app/locales/gd.json
+- app/locales/he.json
+- app/locales/hi.json
+- app/locales/it.json
+- app/locales/ja.json
+- app/locales/ko.json
+- app/locales/lt.json
+- app/locales/nb.json
+- app/locales/nl.json
+- app/locales/pl.json
+- app/locales/pt-br.json
+- app/locales/pt.json
+- app/locales/ru.json
+- app/locales/sv.json
+- app/locales/ta.json
+- app/locales/tr.json
+- app/locales/uk.json
+- app/locales/ur.json
+- app/locales/vi.json
+- app/locales/zh-cn.json
+- app/locales/zh-tw.json
 - lib/ultra_settings.rb
 - lib/ultra_settings/application_view.rb
 - lib/ultra_settings/audit_data_sources.rb
@@ -55,6 +84,7 @@ files:
 - lib/ultra_settings/configuration.rb
 - lib/ultra_settings/configuration_view.rb
 - lib/ultra_settings/field.rb
+- lib/ultra_settings/mini_i18n.rb
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
 - lib/ultra_settings/render_helper.rb

data/AGENTS.md

@@ -1,191 +0,0 @@
-# UltraSettings AI Coding Agent Instructions
-
-## Project Overview
-UltraSettings is a Ruby gem for managing application configuration from multiple sources (environment variables, runtime settings, YAML files) with built-in type safety, validation, and a web UI for documentation.
-
-## Core Architecture
-
-### Configuration Classes (Singleton Pattern)
-- All configuration classes extend `UltraSettings::Configuration` and use Ruby's `Singleton` module
-- Each configuration class has one instance accessible via `.instance`
-- Register configurations globally: `UltraSettings.add(:test)` creates `UltraSettings.test` accessor
-- Configuration classes support inheritance; subclasses maintain separate singleton instances
-
-### Field Definition DSL
-Fields are defined using the `field` class method with extensive options:
-```ruby
-field :timeout, type: :float, default: 1.0, 
-      default_if: ->(val) { val <= 0 },
-      description: "Network timeout in seconds",
-      secret: false
-```
-
-### Multi-Source Value Resolution (Precedence Order)
-1. **Environment Variables** - Highest priority (e.g., `MY_SERVICE_TIMEOUT`)
-2. **Runtime Settings** - Dynamic configuration from external stores (e.g., Redis, `super_settings` gem)
-3. **YAML Files** - File-based defaults with ERB support
-4. **Default Values** - Fallback specified in field definition
-
-### Type System
-Supported types: `:string` (default), `:symbol`, `:integer`, `:float`, `:boolean`, `:datetime`, `:array`
-- Boolean fields auto-generate `?` predicate methods (e.g., `enabled?`)
-- Array type parses CSV strings from env vars, supports proper arrays from YAML
-- Empty strings coerce to `nil` across all sources
-
-## Key Conventions
-
-### Naming Patterns
-- **Configuration class names**: Must end in `Configuration` (e.g., `MyServiceConfiguration`)
-- **Field names**: Match `/\A[a-z_][a-zA-Z0-9_]*\z/` pattern (snake_case)
-- **Environment variable defaults**: `MY_SERVICE_FOO` for `MyServiceConfiguration#foo`
-- **Runtime setting defaults**: `my_service.foo` (lowercase with dots)
-- **YAML keys**: Match field name by default
-
-### Customization Attributes
-Set on configuration classes to override defaults:
-- `env_var_prefix`, `env_var_delimiter`, `env_var_upcase` - Control environment variable naming
-- `runtime_setting_prefix`, `runtime_setting_delimiter`, `runtime_setting_upcase` - Control runtime setting naming
-- `configuration_file` - Specify explicit YAML file path
-- `fields_secret_by_default` - Default secret status (true by default for security)
-- Disable sources entirely: `environment_variables_disabled`, `runtime_settings_disabled`, `yaml_config_disabled`
-
-### Thread Safety
-- All memoized values protected by `Mutex`
-- Override values are thread-local (keyed by `Thread.current.object_id`)
-- Static fields are cached permanently after first access
-
-## Testing Patterns
-
-### Test Setup (spec/spec_helper.rb)
-```ruby
-# Configure YAML path and environment
-UltraSettings.yaml_config_path = Pathname.new(__dir__) + "config"
-UltraSettings.yaml_config_env = "test"
-
-# Register configurations
-UltraSettings.add(:test)
-```
-
-### Overriding Configuration Values
-Use `override!` method for temporary value changes in tests:
-```ruby
-# Via UltraSettings module
-UltraSettings.override!(test: {foo: "bar"}) { ... }
-
-# Via configuration class
-TestConfiguration.override!(foo: "bar") { ... }
-
-# Via configuration instance
-TestConfiguration.instance.override!(foo: "bar") { ... }
-```
-
-### RSpec Integration Example
-```ruby
-RSpec.configure do |config|
-  config.around do |example|
-    if example.metadata[:ultra_settings]
-      UltraSettings.override!(example.metadata[:ultra_settings]) do
-        example.run
-      end
-    end
-  end
-end
-```
-
-### Climate Control for Environment Variables
-Uses `climate_control` gem to safely modify environment variables in tests:
-```ruby
-RSpec.describe "config", env: {TIMEOUT: "5"} do
-  # Test with environment variable set
-end
-```
-
-## Web UI Features
-
-### Mounting the Rack App
-```ruby
-# config.ru or Rails routes
-mount UltraSettings::RackApp.new(color_scheme: :system), at: "/settings"
-```
-
-### Key Capabilities
-- Displays all registered configurations with descriptions
-- Shows field metadata: type, description, sources, but **NOT actual values**
-- Respects secret field marking (values hidden)
-- Includes links to edit runtime settings via `UltraSettings.runtime_settings_url`
-- Views in `lib/ultra_settings/*_view.rb` use ERB templates from `app/` directory
-
-## Common Development Workflows
-
-### Running Tests
-```bash
-bundle exec rake spec  # Default task runs all specs
-bundle exec rspec spec/ultra_settings/configuration_spec.rb  # Specific file
-```
-
-### Checking Code Style
-Uses Standard Ruby style guide (testdouble/standard):
-```bash
-bundle exec standardrb --fix
-```
-
-### Release Process
-- Can only release from `main` branch (enforced in Rakefile)
-- Version stored in `VERSION` file (no hardcoded version in gemspec)
-
-## Special Features
-
-### Static Fields
-- Marked with `static: true`, values never change after first access
-- Cannot be set from runtime settings (initialization-time only)
-- Use for settings referenced during app boot
-
-### Secret Fields
-- All fields secret by default unless `fields_secret_by_default = false`
-- Masked in `__to_hash__` output
-- Runtime settings disabled on secret fields unless `UltraSettings.runtime_settings_secure = true`
-- Secret status can be dynamic via Proc
-
-### Conditional Defaults
-Use `default_if` with Proc or method name to apply defaults based on loaded value:
-```ruby
-field :timeout, default: 1.0, default_if: ->(val) { val <= 0 }
-```
-
-### Introspection Methods
-- `__source__(name)` - Returns which source provided the value (`:env`, `:runtime`, `:yaml`, `:default`)
-- `__value_from_source__(name, source)` - Fetch value from specific source
-- `__to_hash__` - Serialize current configuration as hash (secrets masked)
-
-## Important Implementation Details
-
-### Dynamic Method Generation
-Fields create getter methods via `class_eval` for performance (avoids `method_missing`)
-
-### YAML Configuration
-- Supports environment-specific sections (e.g., `development`, `test`, `production`)
-- Special `shared` section merged with environment-specific config
-- ERB templates evaluated before YAML parsing
-- Files searched in `UltraSettings.yaml_config_path`
-
-### Runtime Settings Integration
-- Must implement `[]` method accepting string argument
-- Optional `array` method for native array support
-- Use `UninitializedRuntimeSettings` during boot to catch premature access
-- `super_settings` gem is recommended companion implementation
-
-## File Organization
-
-- `lib/ultra_settings/configuration.rb` - Core configuration class (630 lines)
-- `lib/ultra_settings/field.rb` - Field metadata and resolution logic
-- `lib/ultra_settings/coerce.rb` - Type coercion utilities
-- `lib/ultra_settings/*.rb` - Supporting classes for web UI, YAML, helpers
-- `spec/test_configs/` - Example configuration classes for testing
-- `spec/config/` - YAML configuration files for tests
-- `app/` - ERB templates and assets for web UI
-
-## Key Dependencies
-- Ruby >= 2.5
-- Development: `rspec`, `climate_control`, `nokogiri`, `bundler`
-- Optional: `super_settings` gem for runtime settings store
-- Rails integration via `railtie.rb` when Rails is detected

data/app/_select_menu.html.erb

@@ -1,53 +0,0 @@
-<div class="ultra-settings-dropdown" id="config-dropdown">
-  <button
-    type="button"
-    class="ultra-settings-dropdown-button"
-    id="config-dropdown-button"
-  >
-    Select Configuration
-  </button>
-
-  <div
-    class="ultra-settings-dropdown-menu"
-    id="config-dropdown-menu"
-    style="display: none;"
-  >
-    <div class="ultra-settings-search-container">
-      <input
-        type="text"
-        id="config-search"
-        placeholder="Search..."
-        autocomplete="off"
-      >
-    </div>
-
-    <ul class="ultra-settings-dropdown-list" id="config-list">
-      <% configurations.each do |config| %>
-        <% config_text = [
-            config.class.name,
-            config.class.description
-          ]
-          config.class.fields.each do |field|
-            config_text << field.name
-            config_text << field.description
-            config_text << field.env_var
-            config_text << field.runtime_setting
-          end
-          search_text = config_text.compact.join(" ").downcase %>
-
-        <li
-          class="ultra-settings-dropdown-item"
-          data-value="config-<%= html_escape(config.class.name) %>"
-          data-label="<%= html_escape(config.class.name) %>"
-          data-search="<%= html_escape(search_text) %>"
-        >
-          <span class="ultra-settings-check-icon"></span>
-
-          <span class="ultra-settings-config-name">
-            <%= html_escape(config.class.name) %>
-          </span>
-        </li>
-      <% end %>
-    </ul>
-  </div>
-</div>