dotlyte 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 526dd14fe18f6f8939c2d146e85b8338c9dabd19e8b8ddce7099828397d990b7
+  data.tar.gz: b174bd56fd0936e55398d51f36c833c472a38a9b684fbfa1753bbe09449b2a84
+SHA512:
+  metadata.gz: 022f372764d0763326c4d8492b7155ba1021e766e4e969d8de29f7ca813df55476661137ef0132120295866a77c9f77ded9ec191321c5f16212d114a720ff8e2
+  data.tar.gz: f00100fb8ed6b0faf536d759d7b3e3357c0687c2333225c28e9341a453f34b36bfeca6bf04e4dec3de7985909ae2921e4b1376212f5d6a8b0137d86375bd2a13

data/README.md

@@ -0,0 +1,30 @@
+# dotlyte — Ruby
+
+The universal `.env` and configuration library for Ruby.
+
+## Installation
+
+```bash
+gem install dotlyte
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "dotlyte"
+```
+
+## Quick Start
+
+```ruby
+require "dotlyte"
+
+config = Dotlyte.load
+config.port           # automatically Integer
+config.debug          # automatically Boolean
+config.database.host  # dot-notation via method_missing
+```
+
+## License
+
+[MIT](../../LICENSE)

data/lib/dotlyte/coercion.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dotlyte
+  # Type coercion engine.
+  module Coercion
+    NULL_VALUES = %w[null none nil].freeze
+    TRUE_VALUES = %w[true yes 1 on].freeze
+    FALSE_VALUES = %w[false no 0 off].freeze
+
+    # Auto-convert a string value to the correct Ruby type.
+    #
+    # @param value [Object] the value to coerce
+    # @return [Object] the coerced value
+    def self.coerce(value)
+      return value unless value.is_a?(String)
+
+      stripped = value.strip
+      lower = stripped.downcase
+
+      # Null
+      return nil if stripped.empty? || NULL_VALUES.include?(lower)
+
+      # Boolean
+      return true if TRUE_VALUES.include?(lower)
+      return false if FALSE_VALUES.include?(lower)
+
+      # Integer
+      return Integer(stripped) if stripped.match?(/\A-?\d+\z/)
+
+      # Float
+      if stripped.include?(".") && stripped.match?(/\A-?\d+\.\d+\z/)
+        return Float(stripped)
+      end
+
+      # List (comma-separated)
+      if stripped.include?(",")
+        return stripped.split(",").map { |item| coerce(item.strip) }
+      end
+
+      # String
+      stripped
+    end
+
+    # Recursively coerce all string values in a hash.
+    def self.coerce_hash(data)
+      data.each_with_object({}) do |(key, value), result|
+        result[key] = case value
+                      when Hash then coerce_hash(value)
+                      when String then coerce(value)
+                      else value
+                      end
+      end
+    end
+  end
+end

data/lib/dotlyte/config.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+module Dotlyte
+  # Immutable configuration object with dot-notation access via method_missing.
+  class Config
+    # @param data [Hash] the configuration data
+    # @param schema [Hash<String, SchemaRule>, nil] optional schema for validation
+    # @param sensitive_keys [Set<String>] keys to redact in output
+    def initialize(data, schema: nil, sensitive_keys: Set.new)
+      @data = data.freeze
+      @schema = schema
+      @sensitive_keys = sensitive_keys
+    end
+
+    # Safe access with dot-notation and optional default.
+    #
+    # @param key [String] dot-notation key (e.g., "database.host")
+    # @param default_value [Object] fallback if key is missing
+    # @return [Object] the config value or default
+    def get(key, default_value = nil)
+      parts = key.to_s.split(".")
+      val = @data
+
+      parts.each do |part|
+        if val.is_a?(Hash)
+          val = val.key?(part) ? val[part] : val[part.to_sym]
+          return default_value if val.nil?
+        else
+          return default_value
+        end
+      end
+
+      val
+    end
+
+    # Required access — raises MissingKeyError if missing.
+    #
+    # @param key [String] the config key
+    # @return [Object] the config value
+    # @raise [MissingKeyError] if the key is missing
+    def require(key)
+      val = get(key)
+      if val.nil?
+        raise MissingKeyError.new(
+          "Required config key '#{key}' is missing. " \
+          "Set it in your .env file or as an environment variable.",
+          key: key
+        )
+      end
+      val
+    end
+
+    # Require multiple keys at once.
+    #
+    # @param keys [Array<String>] the config keys
+    # @return [Array<Object>] the values
+    # @raise [MissingKeyError] if any key is missing
+    def require_keys(*keys)
+      keys.flatten.map { |k| self.require(k) }
+    end
+
+    # Check if a key exists.
+    def has?(key)
+      !get(key).nil?
+    end
+
+    # Get a scoped sub-config (returns a new Config for a nested hash).
+    #
+    # @param prefix [String] dot-notation prefix
+    # @return [Config] scoped config
+    def scope(prefix)
+      sub = get(prefix)
+      raise Error.new("No config section found for '#{prefix}'", key: prefix) unless sub.is_a?(Hash)
+
+      scoped_sensitive = Set.new
+      @sensitive_keys.each do |sk|
+        scoped_sensitive.add(sk.delete_prefix("#{prefix}.")) if sk.start_with?("#{prefix}.")
+      end
+
+      Config.new(sub, schema: nil, sensitive_keys: scoped_sensitive)
+    end
+
+    # All top-level keys.
+    def keys
+      @data.keys
+    end
+
+    # All keys flattened via dot-notation.
+    def to_flat_keys
+      flat_keys(@data)
+    end
+
+    # Flatten the config to a single-level hash.
+    def to_flat_hash
+      flatten(@data)
+    end
+
+    # Convert to a plain Hash (deep copy).
+    def to_h
+      deep_dup(@data)
+    end
+
+    # Return a redacted hash with sensitive values masked.
+    def to_h_redacted
+      Masking.redact(deep_dup(@data), @sensitive_keys)
+    end
+
+    # Serialize to JSON.
+    def to_json(*_args)
+      JSON.generate(to_h)
+    end
+
+    # Write config to a file (JSON or YAML).
+    def write_to(path)
+      ext = File.extname(path).downcase
+      content = case ext
+                when ".json"
+                  JSON.pretty_generate(to_h)
+                when ".yaml", ".yml"
+                  require "yaml"
+                  YAML.dump(to_h)
+                else
+                  raise Error, "Unsupported output format: #{ext}"
+                end
+      File.write(path, content)
+    end
+
+    # Validate against schema. Returns array of violations.
+    def validate(schema = nil)
+      s = schema || @schema
+      return [] unless s
+
+      Validator.validate(deep_dup(@data), s)
+    end
+
+    # Validate and raise on failure.
+    def assert_valid!(schema = nil)
+      s = schema || @schema
+      return unless s
+
+      Validator.assert_valid!(deep_dup(@data), s)
+    end
+
+    # Support dot-notation via method_missing.
+    def method_missing(name, *args)
+      key = name.to_s
+      if @data.key?(key)
+        val = @data[key]
+        val.is_a?(Hash) ? Config.new(val, sensitive_keys: scoped_sensitive_keys(key)) : val
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @data.key?(name.to_s) || super
+    end
+
+    def inspect
+      "Config(#{to_h_redacted})"
+    end
+
+    alias_method :to_s, :inspect
+
+    private
+
+    def deep_dup(hash)
+      hash.each_with_object({}) do |(k, v), out|
+        out[k] = v.is_a?(Hash) ? deep_dup(v) : v
+      end
+    end
+
+    def flat_keys(hash, prefix = "", out = [])
+      hash.each do |key, value|
+        full = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+        if value.is_a?(Hash)
+          flat_keys(value, full, out)
+        else
+          out << full
+        end
+      end
+      out
+    end
+
+    def flatten(hash, prefix = "", out = {})
+      hash.each do |key, value|
+        full = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+        if value.is_a?(Hash)
+          flatten(value, full, out)
+        else
+          out[full] = value
+        end
+      end
+      out
+    end
+
+    def scoped_sensitive_keys(key)
+      scoped = Set.new
+      prefix = "#{key}."
+      @sensitive_keys.each do |sk|
+        scoped.add(sk.delete_prefix(prefix)) if sk.start_with?(prefix)
+      end
+      scoped
+    end
+  end
+end

data/lib/dotlyte/encryption.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "securerandom"
+
+module Dotlyte
+  # AES-256-GCM encryption/decryption for DOTLYTE v2 (SOPS-style).
+  #
+  # Format: ENC[aes-256-gcm,iv:<base64>,data:<base64>,tag:<base64>]
+  module Encryption
+    PREFIX = "ENC["
+    GCM_TAG_BYTES = 16
+    IV_BYTES = 12
+    KEY_BYTES = 32
+
+    # Check whether a string is an encrypted SOPS-style value.
+    def self.encrypted?(value)
+      value.is_a?(String) && value.start_with?(PREFIX) && value.end_with?("]")
+    end
+
+    # Generate a random 32-byte key as hex.
+    def self.generate_key
+      SecureRandom.hex(KEY_BYTES)
+    end
+
+    # Encrypt a plaintext string with a hex-encoded 256-bit key.
+    #
+    # @param plaintext [String]
+    # @param key_hex [String] 64-char hex string
+    # @return [String] SOPS-style encrypted value
+    def self.encrypt_value(plaintext, key_hex)
+      key_bytes = [key_hex].pack("H*")
+      raise Error, "Key must be 32 bytes, got #{key_bytes.bytesize}" unless key_bytes.bytesize == KEY_BYTES
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = key_bytes
+      iv = cipher.random_iv
+      cipher.auth_data = ""
+
+      ciphertext = cipher.update(plaintext) + cipher.final
+      tag = cipher.auth_tag(GCM_TAG_BYTES)
+
+      iv_b64 = Base64.strict_encode64(iv)
+      data_b64 = Base64.strict_encode64(ciphertext)
+      tag_b64 = Base64.strict_encode64(tag)
+
+      "ENC[aes-256-gcm,iv:#{iv_b64},data:#{data_b64},tag:#{tag_b64}]"
+    rescue OpenSSL::Cipher::CipherError => e
+      raise Error, "Encryption failed: #{e.message}"
+    end
+
+    # Decrypt a SOPS-style encrypted value.
+    #
+    # @param encrypted [String]
+    # @param key_hex [String] 64-char hex string
+    # @return [String] plaintext
+    def self.decrypt_value(encrypted, key_hex)
+      key_bytes = [key_hex].pack("H*")
+      raise Error, "Key must be 32 bytes, got #{key_bytes.bytesize}" unless key_bytes.bytesize == KEY_BYTES
+
+      inner = encrypted
+      inner = inner[4..-2] if inner.start_with?("ENC[") && inner.end_with?("]")
+
+      parts = {}
+      inner.split(",").each do |part|
+        part = part.strip
+        if part.start_with?("iv:")
+          parts[:iv] = part[3..]
+        elsif part.start_with?("data:")
+          parts[:data] = part[5..]
+        elsif part.start_with?("tag:")
+          parts[:tag] = part[4..]
+        end
+      end
+
+      iv = Base64.strict_decode64(parts[:iv])
+      data = Base64.strict_decode64(parts[:data])
+      tag = Base64.strict_decode64(parts[:tag])
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = key_bytes
+      cipher.iv = iv
+      cipher.auth_tag = tag
+      cipher.auth_data = ""
+
+      cipher.update(data) + cipher.final
+    rescue OpenSSL::Cipher::CipherError => e
+      raise DecryptionError, "Decryption failed: #{e.message}"
+    end
+
+    # Decrypt all ENC[...] values in a hash.
+    def self.decrypt_hash(data, key_hex)
+      data.each do |k, v|
+        data[k] = decrypt_value(v, key_hex) if encrypted?(v)
+      end
+    end
+
+    # Resolve encryption key from environment / key file.
+    def self.resolve_encryption_key(env_name = nil)
+      if env_name && !env_name.empty?
+        val = ENV["DOTLYTE_KEY_#{env_name.upcase}"]
+        return val if val && !val.empty?
+      end
+
+      val = ENV["DOTLYTE_KEY"]
+      return val if val && !val.empty?
+
+      key_file = ".dotlyte-keys"
+      if File.exist?(key_file)
+        line = File.readlines(key_file, chomp: true).first&.strip
+        return line if line && !line.empty?
+      end
+
+      nil
+    end
+  end
+end

data/lib/dotlyte/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dotlyte
+  # Base error class for all DOTLYTE errors.
+  class Error < StandardError
+    # @return [String, nil] the config key that caused the error
+    attr_reader :key
+
+    def initialize(message, key: nil)
+      super(message)
+      @key = key
+    end
+  end
+
+  # Raised when require() encounters a missing key.
+  class MissingKeyError < Error
+    # @return [Array<String>] the source files that were checked
+    attr_reader :sources_checked
+
+    def initialize(message, key: nil, sources_checked: [])
+      super(message, key: key)
+      @sources_checked = sources_checked
+    end
+  end
+
+  # Raised when a config file has invalid syntax.
+  class ParseError < Error; end
+
+  # Raised when a config file cannot be read or found.
+  class FileError < Error
+    # @return [String, nil] the file path
+    attr_reader :file_path
+
+    def initialize(message, file_path: nil, key: nil)
+      super(message, key: key)
+      @file_path = file_path
+    end
+  end
+
+  # Raised when schema validation fails.
+  class ValidationError < Error
+    # @return [Array<SchemaViolation>] the violations found
+    attr_reader :violations
+
+    def initialize(message, violations: [], key: nil)
+      super(message, key: key)
+      @violations = violations
+    end
+  end
+
+  # Raised when variable interpolation fails (e.g., circular reference).
+  class InterpolationError < Error; end
+
+  # Raised when decryption of an encrypted value fails.
+  class DecryptionError < Error; end
+end

data/lib/dotlyte/interpolation.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Dotlyte
+  # Variable interpolation engine for DOTLYTE v2.
+  #
+  # Supports ${VAR}, ${VAR:-default}, ${VAR:?error}, and $$ escape.
+  module Interpolation
+    # Interpolate ${VAR} references in a flat string hash.
+    #
+    # @param data [Hash<String, String>] key-value pairs
+    # @param context [Hash<String, String>] additional context
+    # @return [Hash<String, String>] resolved values
+    def self.interpolate(data, context = {})
+      resolved = {}
+      resolving = Set.new
+
+      data.each_key { |key| resolve(key, data, context, resolved, resolving) }
+      resolved
+    end
+
+    # Interpolate a deep hash (nested values).
+    #
+    # @param data [Hash] deep hash
+    # @param context [Hash] additional context
+    # @return [Hash] resolved deep hash
+    def self.interpolate_deep(data, context = {})
+      flat = flatten_to_strings(data)
+      ctx_flat = flatten_to_strings(context)
+      resolved = interpolate(flat, ctx_flat)
+
+      result = deep_copy(data)
+      resolved.each do |key, value|
+        set_nested(result, key, Coercion.coerce(value))
+      end
+      result
+    end
+
+    class << self
+      private
+
+      def resolve(key, data, context, resolved, resolving)
+        return resolved[key] if resolved.key?(key)
+
+        if resolving.include?(key)
+          raise InterpolationError.new(
+            "Circular reference detected for variable: #{key}", key: key
+          )
+        end
+
+        raw = data[key]
+        if raw.nil?
+          return context[key] if context.key?(key)
+
+          env = ENV[key.upcase]
+          return env || ""
+        end
+
+        resolving.add(key)
+        val = resolve_string(raw.to_s, data, context, resolved, resolving)
+        resolving.delete(key)
+        resolved[key] = val
+        val
+      end
+
+      def resolve_string(s, data, context, resolved, resolving)
+        s = s.gsub("$$", "\x00DOLLAR\x00")
+        result = +""
+        i = 0
+
+        while i < s.length
+          if i + 1 < s.length && s[i] == "$" && s[i + 1] == "{"
+            i += 2
+            depth = 1
+            inner = +""
+            while i < s.length && depth.positive?
+              ch = s[i]
+              if ch == "{"
+                depth += 1
+              elsif ch == "}"
+                depth -= 1
+                if depth.zero?
+                  i += 1
+                  break
+                end
+              end
+              inner << ch
+              i += 1
+            end
+            result << resolve_reference(inner, data, context, resolved, resolving)
+          else
+            result << s[i]
+            i += 1
+          end
+        end
+
+        result.gsub("\x00DOLLAR\x00", "$")
+      end
+
+      def resolve_reference(inner, data, context, resolved, resolving)
+        err_idx = inner.index(":?")
+        def_idx = inner.index(":-")
+
+        if err_idx
+          var_name = inner[0...err_idx].strip
+          error_msg = inner[(err_idx + 2)..]
+        elsif def_idx
+          var_name = inner[0...def_idx].strip
+          fallback = inner[(def_idx + 2)..]
+        else
+          var_name = inner.strip
+        end
+
+        lower = var_name.downcase
+
+        # Same-file
+        if data.key?(lower)
+          val = resolve(lower, data, context, resolved, resolving)
+          return val unless val.empty?
+        end
+
+        # Context
+        if context.key?(lower)
+          val = context[lower]
+          return val if val && !val.empty?
+        end
+
+        # Env
+        env = ENV[var_name] || ENV[var_name.upcase]
+        return env if env && !env.empty?
+
+        # Not found
+        if error_msg
+          raise InterpolationError.new("Required variable '#{var_name}': #{error_msg}", key: var_name)
+        end
+
+        fallback || ""
+      end
+
+      def flatten_to_strings(hash, prefix = "", out = {})
+        hash.each do |key, value|
+          full_key = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+          if value.is_a?(Hash)
+            flatten_to_strings(value, full_key, out)
+          elsif !value.nil?
+            out[full_key] = value.to_s
+          end
+        end
+        out
+      end
+
+      def deep_copy(hash)
+        hash.each_with_object({}) do |(k, v), result|
+          result[k] = v.is_a?(Hash) ? deep_copy(v) : v
+        end
+      end
+
+      def set_nested(hash, key, value)
+        parts = key.split(".")
+        current = hash
+        parts[0..-2].each do |part|
+          current[part] ||= {}
+          current[part] = {} unless current[part].is_a?(Hash)
+          current = current[part]
+        end
+        current[parts.last] = value
+      end
+    end
+  end
+end