RubyGems - rhales - Versions diffs - 0.3.0 → 0.5.3 - Mend

rhales 0.3.0 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (116) hide show

checksums.yaml +4 -4
data/.github/renovate.json5 +52 -0
data/.github/workflows/ci.yml +123 -0
data/.github/workflows/claude-code-review.yml +69 -0
data/.github/workflows/claude.yml +49 -0
data/.github/workflows/code-smells.yml +146 -0
data/.github/workflows/ruby-lint.yml +78 -0
data/.github/workflows/yardoc.yml +126 -0
data/.gitignore +55 -0
data/.pr_agent.toml +63 -0
data/.pre-commit-config.yaml +89 -0
data/.prettierignore +8 -0
data/.prettierrc +38 -0
data/.reek.yml +98 -0
data/.rubocop.yml +428 -0
data/.serena/.gitignore +3 -0
data/.yardopts +56 -0
data/CHANGELOG.md +44 -0
data/CLAUDE.md +1 -2
data/Gemfile +29 -0
data/Gemfile.lock +189 -0
data/README.md +706 -589
data/Rakefile +46 -0
data/debug_context.rb +25 -0
data/demo/rhales-roda-demo/.gitignore +7 -0
data/demo/rhales-roda-demo/Gemfile +32 -0
data/demo/rhales-roda-demo/Gemfile.lock +151 -0
data/demo/rhales-roda-demo/MAIL.md +405 -0
data/demo/rhales-roda-demo/README.md +376 -0
data/demo/rhales-roda-demo/RODA-TEMPLATE-ENGINES.md +192 -0
data/demo/rhales-roda-demo/Rakefile +49 -0
data/demo/rhales-roda-demo/app.rb +325 -0
data/demo/rhales-roda-demo/bin/rackup +26 -0
data/demo/rhales-roda-demo/config.ru +13 -0
data/demo/rhales-roda-demo/db/migrate/001_create_rodauth_tables.rb +266 -0
data/demo/rhales-roda-demo/db/migrate/002_create_rodauth_password_tables.rb +79 -0
data/demo/rhales-roda-demo/db/migrate/003_add_admin_account.rb +68 -0
data/demo/rhales-roda-demo/templates/change_login.rue +31 -0
data/demo/rhales-roda-demo/templates/change_password.rue +36 -0
data/demo/rhales-roda-demo/templates/close_account.rue +31 -0
data/demo/rhales-roda-demo/templates/create_account.rue +40 -0
data/demo/rhales-roda-demo/templates/dashboard.rue +150 -0
data/demo/rhales-roda-demo/templates/home.rue +78 -0
data/demo/rhales-roda-demo/templates/layouts/main.rue +168 -0
data/demo/rhales-roda-demo/templates/login.rue +65 -0
data/demo/rhales-roda-demo/templates/logout.rue +25 -0
data/demo/rhales-roda-demo/templates/reset_password.rue +26 -0
data/demo/rhales-roda-demo/templates/verify_account.rue +27 -0
data/demo/rhales-roda-demo/test_full_output.rb +27 -0
data/demo/rhales-roda-demo/test_simple.rb +24 -0
data/docs/.gitignore +9 -0
data/docs/architecture/data-flow.md +499 -0
data/examples/dashboard-with-charts.rue +271 -0
data/examples/form-with-validation.rue +180 -0
data/examples/simple-page.rue +61 -0
data/examples/vue.rue +136 -0
data/generate-json-schemas.ts +158 -0
data/json_schemer_migration_summary.md +172 -0
data/lib/rhales/adapters/base_auth.rb +2 -0
data/lib/rhales/adapters/base_request.rb +2 -0
data/lib/rhales/adapters/base_session.rb +2 -0
data/lib/rhales/adapters.rb +7 -0
data/lib/rhales/configuration.rb +161 -1
data/lib/rhales/core/context.rb +354 -0
data/lib/rhales/{rue_document.rb → core/rue_document.rb} +59 -43
data/lib/rhales/{template_engine.rb → core/template_engine.rb} +80 -33
data/lib/rhales/core/view.rb +529 -0
data/lib/rhales/{view_composition.rb → core/view_composition.rb} +81 -9
data/lib/rhales/core.rb +9 -0
data/lib/rhales/errors/hydration_collision_error.rb +2 -0
data/lib/rhales/errors.rb +2 -0
data/lib/rhales/hydration/earliest_injection_detector.rb +153 -0
data/lib/rhales/hydration/hydration_data_aggregator.rb +487 -0
data/lib/rhales/hydration/hydration_endpoint.rb +215 -0
data/lib/rhales/hydration/hydration_injector.rb +175 -0
data/lib/rhales/{hydration_registry.rb → hydration/hydration_registry.rb} +2 -0
data/lib/rhales/hydration/hydrator.rb +102 -0
data/lib/rhales/hydration/link_based_injection_detector.rb +195 -0
data/lib/rhales/hydration/mount_point_detector.rb +109 -0
data/lib/rhales/hydration/safe_injection_validator.rb +103 -0
data/lib/rhales/hydration.rb +13 -0
data/lib/rhales/{refinements → integrations/refinements}/require_refinements.rb +7 -13
data/lib/rhales/{tilt.rb → integrations/tilt.rb} +26 -18
data/lib/rhales/integrations.rb +6 -0
data/lib/rhales/middleware/json_responder.rb +191 -0
data/lib/rhales/middleware/schema_validator.rb +300 -0
data/lib/rhales/middleware.rb +6 -0
data/lib/rhales/parsers/handlebars_parser.rb +2 -0
data/lib/rhales/parsers/rue_format_parser.rb +55 -36
data/lib/rhales/parsers.rb +9 -0
data/lib/rhales/{csp.rb → security/csp.rb} +27 -3
data/lib/rhales/utils/json_serializer.rb +114 -0
data/lib/rhales/utils/logging_helpers.rb +75 -0
data/lib/rhales/utils/schema_extractor.rb +132 -0
data/lib/rhales/utils/schema_generator.rb +194 -0
data/lib/rhales/utils.rb +40 -0
data/lib/rhales/version.rb +5 -1
data/lib/rhales.rb +47 -19
data/lib/tasks/rhales_schema.rake +197 -0
data/package.json +10 -0
data/pnpm-lock.yaml +345 -0
data/pnpm-workspace.yaml +2 -0
data/proofs/error_handling.rb +79 -0
data/proofs/expanded_object_inheritance.rb +82 -0
data/proofs/partial_context_scoping_fix.rb +168 -0
data/proofs/ui_context_partial_inheritance.rb +236 -0
data/rhales.gemspec +14 -6
data/schema_vs_data_comparison.md +254 -0
data/test_direct_access.rb +36 -0
metadata +142 -18
data/CLAUDE.locale.txt +0 -7
data/lib/rhales/context.rb +0 -240
data/lib/rhales/hydration_data_aggregator.rb +0 -220
data/lib/rhales/hydrator.rb +0 -141
data/lib/rhales/parsers/handlebars-grammar-review.txt +0 -39
data/lib/rhales/view.rb +0 -412

data/lib/rhales/errors/hydration_collision_error.rb CHANGED Viewed

@@ -1,3 +1,5 @@
+# lib/rhales/errors/hydration_collision_error.rb
+#
 # frozen_string_literal: true
 module Rhales

data/lib/rhales/errors.rb CHANGED Viewed

@@ -1,4 +1,6 @@
 # lib/rhales/errors.rb
+#
+# frozen_string_literal: true
 module Rhales
   class Error < StandardError; end

data/lib/rhales/hydration/earliest_injection_detector.rb ADDED Viewed

@@ -0,0 +1,153 @@
+# lib/rhales/hydration/earliest_injection_detector.rb
+#
+# frozen_string_literal: true
+require 'strscan'
+require_relative 'safe_injection_validator'
+module Rhales
+  # Detects the earliest safe injection points in HTML head and body sections
+  # for optimal hydration script placement performance
+  #
+  # ## Injection Priority Order
+  #
+  # For `<head></head>` section:
+  # 1. After the last `<link>` tag
+  # 2. After the last `<meta>` tag
+  # 3. After the first `<script>` tag (assuming early scripts are intentional)
+  # 4. Before the `</head>` tag
+  #
+  # If no `<head>` but there is `<body>`:
+  # - Before the `<body>` tag
+  #
+  # All injection points are validated for safety using SafeInjectionValidator
+  # to prevent injection inside unsafe contexts (scripts, styles, comments).
+  class EarliestInjectionDetector
+    def detect(template_html)
+      scanner = StringScanner.new(template_html)
+      validator = SafeInjectionValidator.new(template_html)
+      # Try head section injection points first
+      head_injection_point = detect_head_injection_point(scanner, validator, template_html)
+      return head_injection_point if head_injection_point
+      # Fallback to body tag injection
+      body_injection_point = detect_body_injection_point(scanner, validator, template_html)
+      return body_injection_point if body_injection_point
+      # No suitable injection point found
+      nil
+    end
+    private
+    def detect_head_injection_point(scanner, validator, template_html)
+      # Find head section bounds
+      head_start, head_end = find_head_section(template_html)
+      return nil unless head_start && head_end
+      # Try injection points in priority order within head section
+      injection_candidates = [
+        find_after_last_link(template_html, head_start, head_end),
+        find_after_last_meta(template_html, head_start, head_end),
+        find_after_first_script(template_html, head_start, head_end),
+        head_end # Before </head>
+      ].compact
+      # Return first safe injection point
+      injection_candidates.each do |position|
+        safe_position = find_safe_injection_position(validator, position)
+        return safe_position if safe_position
+      end
+      nil
+    end
+    def detect_body_injection_point(scanner, validator, template_html)
+      scanner.pos = 0
+      # Find opening <body> tag
+      if scanner.scan_until(/<body\b[^>]*>/i)
+        body_start = scanner.pos - scanner.matched.length
+        safe_position = find_safe_injection_position(validator, body_start)
+        return safe_position if safe_position
+      end
+      nil
+    end
+    def find_head_section(template_html)
+      scanner = StringScanner.new(template_html)
+      # Find opening <head> tag
+      return nil unless scanner.scan_until(/<head\b[^>]*>/i)
+      head_start = scanner.pos
+      # Find closing </head> tag
+      return nil unless scanner.scan_until(/<\/head>/i)
+      head_end = scanner.pos - scanner.matched.length
+      [head_start, head_end]
+    end
+    def find_after_last_link(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+      last_link_end = nil
+      while scanner.scan_until(/<link\b[^>]*\/?>/i)
+        last_link_end = scanner.pos
+      end
+      last_link_end ? head_start + last_link_end : nil
+    end
+    def find_after_last_meta(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+      last_meta_end = nil
+      while scanner.scan_until(/<meta\b[^>]*\/?>/i)
+        last_meta_end = scanner.pos
+      end
+      last_meta_end ? head_start + last_meta_end : nil
+    end
+    def find_after_first_script(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+      # Find first script opening tag
+      if scanner.scan_until(/<script\b[^>]*>/i)
+        script_start = scanner.pos - scanner.matched.length
+        # Find corresponding closing tag
+        if scanner.scan_until(/<\/script>/i)
+          first_script_end = scanner.pos
+          return head_start + first_script_end
+        end
+      end
+      nil
+    end
+    def find_safe_injection_position(validator, preferred_position)
+      return nil unless preferred_position
+      # First check if the preferred position is safe
+      return preferred_position if validator.safe_injection_point?(preferred_position)
+      # Try to find a safe position before the preferred position
+      safe_before = validator.nearest_safe_point_before(preferred_position)
+      return safe_before if safe_before
+      # As a last resort, try after the preferred position
+      safe_after = validator.nearest_safe_point_after(preferred_position)
+      return safe_after if safe_after
+      # No safe position found
+      nil
+    end
+  end
+end

data/lib/rhales/hydration/hydration_data_aggregator.rb ADDED Viewed

@@ -0,0 +1,487 @@
+# lib/rhales/hydration_data_aggregator.rb
+#
+# frozen_string_literal: true
+require 'json'
+require_relative '../core/template_engine'
+require_relative '../errors'
+module Rhales
+  # HydrationDataAggregator traverses the ViewComposition and executes
+  # all <schema> sections to produce a single, merged JSON structure.
+  #
+  # This class implements the server-side data aggregation phase of the
+  # two-pass rendering model, handling:
+  # - Traversal of the template dependency tree
+  # - Direct serialization of props for <schema> sections
+  # - Merge strategies (deep, shallow, strict)
+  # - Collision detection and error reporting
+  #
+  # The aggregator replaces the HydrationRegistry by performing all
+  # data merging in a single, coordinated pass.
+  class HydrationDataAggregator
+    include Rhales::Utils::LoggingHelpers
+    class JSONSerializationError < StandardError; end
+    def initialize(context)
+      @context = context
+      @window_attributes = {}
+      @merged_data = {}
+      @schema_cache = {}
+      @schemas_dir = File.join(Dir.pwd, 'public/schemas')
+    end
+    # Aggregate all hydration data from the view composition
+    def aggregate(composition)
+      log_timed_operation(Rhales.logger, :debug, 'Schema aggregation started',
+        template_count: composition.template_names.size
+      ) do
+        composition.each_document_in_render_order do |template_name, parser|
+          process_template(template_name, parser)
+        end
+        @merged_data
+      end
+    end
+    private
+    # Log hydration schema mismatch using configured format
+    def log_hydration_mismatch(template_path, window_attr, expected, actual, missing, extra, data_size)
+      format = Rhales.config.hydration_mismatch_format || :compact
+      formatter = case format
+      when :sidebyside
+        format_sidebyside(template_path, window_attr, expected, actual, missing, extra, data_size)
+      when :multiline
+        format_multiline(template_path, window_attr, expected, actual, missing, extra, data_size)
+      when :compact
+        format_compact(template_path, window_attr, expected, actual, missing, extra, data_size)
+      when :json
+        format_json(template_path, window_attr, expected, actual, missing, extra, data_size)
+      else
+        raise ArgumentError, "Unknown hydration_mismatch_format: #{format}. Valid: :compact, :multiline, :sidebyside, :json"
+      end
+      Rhales.logger.warn formatter
+    end
+    # Format: Side-by-side comparison (most visual, for development)
+    def format_sidebyside(template_path, window_attr, expected, actual, missing, extra, data_size)
+      # Determine authority: schema (default) or data
+      authority = Rhales.config.hydration_authority || :schema
+      lines = []
+      lines << 'Hydration schema mismatch'
+      lines << "  Template: #{template_path}"
+      lines << "  Window: #{window_attr} (#{data_size} keys)"
+      lines << ''
+      if authority == :schema
+        # Schema is correct, data needs fixing
+        lines << '  Schema (correct) │ Data (fix)'
+        lines << '  ─────────────────┼────────────'
+        # Show all expected keys with their status
+        expected.each do |key|
+          lines << if actual.include?(key)
+            "  #{key.ljust(17)}│ ✓ #{key}"
+          else
+            "  #{key.ljust(17)}│ ✗ missing  ← add to data source"
+                   end
+        end
+        # Show extra keys that shouldn't be in data
+        extra.each do |key|
+          lines << "  (not in schema)  │ ✗ #{key}  ← remove from data source"
+        end
+      else
+        # Data is correct, schema needs fixing
+        lines << '  Schema (fix)     │ Data (correct)'
+        lines << '  ─────────────────┼───────────────'
+        # Show all actual keys with their status
+        actual.each do |key|
+          lines << if expected.include?(key)
+            "  #{key.ljust(17)}│ ✓ #{key}"
+          else
+            "  [missing]        │ ✓ #{key}  ← add to schema"
+                   end
+        end
+        # Show keys in schema but not in data
+        missing.each do |key|
+          lines << "  #{key.ljust(17)}│ (not in data)  ← remove from schema"
+        end
+      end
+      lines.join("\n")
+    end
+    # Format: Multi-line with visual indicators (balanced)
+    def format_multiline(template_path, window_attr, expected, actual, missing, extra, data_size)
+      # Check if order changed (same keys, different positions)
+      order_changed = (expected.to_set == actual.to_set) && (expected != actual)
+      # Find keys that moved position
+      moved_keys = if order_changed
+        (expected & actual).select do |k|
+          expected.index(k) != actual.index(k)
+        end
+      else
+        []
+      end
+      lines = []
+      lines << 'Hydration schema mismatch'
+      lines << "  Template: #{template_path}"
+      lines << "  Window: #{window_attr}"
+      lines << "  Data size: #{data_size}"
+      if missing.any?
+        lines << "  ✗ Schema expects (#{missing.size}): #{missing.join(', ')}"
+      end
+      if extra.any?
+        lines << "  + Data provides (#{extra.size}): #{extra.join(', ')}"
+      end
+      if moved_keys.any?
+        lines << "  ↔ Order changed (#{moved_keys.size}): #{moved_keys.join(', ')}"
+      end
+      lines.join("\n")
+    end
+    # Format: Single line compact (for production)
+    def format_compact(template_path, window_attr, _expected, _actual, missing, extra, data_size)
+      parts = []
+      parts << "#{missing.size} missing" if missing.any?
+      parts << "#{extra.size} extra" if extra.any?
+      summary = parts.join(', ')
+      metadata = {
+        template: template_path,
+        window_attribute: window_attr,
+        missing_keys: missing,
+        extra_keys: extra,
+        client_data_size: data_size,
+      }
+      # Use existing metadata formatter
+      metadata_str = metadata.map do |k, v|
+        "#{k}=#{format_metadata_value(v)}"
+      end.join(' ')
+      "Schema mismatch (#{summary}): #{metadata_str}"
+    end
+    # Format: JSON (for structured logging systems)
+    def format_json(template_path, window_attr, expected, actual, missing, extra, data_size)
+      require 'json'
+      authority = Rhales.config.hydration_authority || :schema
+      # Check if order changed
+      order_changed = (expected.to_set == actual.to_set) && (expected != actual)
+      moved_keys = if order_changed
+        (expected & actual).select { |k| expected.index(k) != actual.index(k) }
+      else
+        []
+      end
+      data = {
+        event: 'hydration_schema_mismatch',
+        template: template_path,
+        window_attribute: window_attr,
+        authority: authority,
+        schema: {
+          expected_keys: expected,
+          key_count: expected.size,
+        },
+        data: {
+          actual_keys: actual,
+          key_count: data_size,
+        },
+        diff: {
+          missing_keys: missing,
+          missing_count: missing.size,
+          extra_keys: extra,
+          extra_count: extra.size,
+          order_changed: order_changed,
+          moved_keys: moved_keys,
+        },
+      }
+      JSON.generate(data)
+    end
+    # Format values for compact metadata output
+    def format_metadata_value(value)
+      case value
+      when Array
+        if value.empty?
+          '[]'
+        else
+          "[#{value.join(', ')}]"
+        end
+      when String
+        value.include?(' ') ? "\"#{value}\"" : value
+      else
+        value.to_s
+      end
+    end
+    def process_template(template_name, parser)
+      # Process schema section
+      if parser.schema_lang
+        log_timed_operation(Rhales.logger, :debug, 'Schema validation',
+          template: template_name,
+          schema_lang: parser.schema_lang
+        ) do
+          process_schema_section(template_name, parser)
+        end
+      end
+    end
+    # Process schema section: Direct JSON serialization
+    def process_schema_section(template_name, parser)
+      window_attr = parser.schema_window || 'data'
+      merge_strategy = parser.schema_merge_strategy
+      # Extract client data for validation
+      client_data = @context.client || {}
+      schema_content = parser.section('schema')
+      expected_keys = extract_expected_keys(template_name, schema_content) if schema_content
+      # Build template path for error reporting
+      template_path = build_template_path_for_schema(parser)
+      # Log schema validation details
+      if expected_keys && expected_keys.any?
+        actual_keys = client_data.keys.map(&:to_s)
+        missing_keys = expected_keys - actual_keys
+        extra_keys = actual_keys - expected_keys
+        if missing_keys.any? || extra_keys.any?
+          log_hydration_mismatch(
+            Rhales.pretty_path(template_path),
+            window_attr,
+            expected_keys,
+            actual_keys,
+            missing_keys,
+            extra_keys,
+            client_data.size,
+          )
+        else
+          log_with_metadata(Rhales.logger, :debug, 'Schema validation passed',
+            template: Rhales.pretty_path(template_path),
+            window_attribute: window_attr,
+            key_count: expected_keys.size,
+            client_data_size: client_data.size
+          )
+        end
+      end
+      # Direct serialization of client data (no template interpolation)
+      processed_data = @context.client
+      # Check for collisions only if the data is not empty
+      if @window_attributes.key?(window_attr) && merge_strategy.nil? && !empty_data?(processed_data)
+        existing = @window_attributes[window_attr]
+        existing_data = @merged_data[window_attr]
+        # Only raise collision error if existing data is also not empty
+        unless empty_data?(existing_data)
+          raise ::Rhales::HydrationCollisionError.new(window_attr, existing[:path], template_path)
+        end
+      end
+      # Merge or set the data
+      @merged_data[window_attr] = if @merged_data.key?(window_attr)
+        merge_data(
+          @merged_data[window_attr],
+          processed_data,
+          merge_strategy || 'deep',
+          window_attr,
+          template_path,
+        )
+      else
+        processed_data
+                                  end
+      # Track the window attribute
+      @window_attributes[window_attr] = {
+        path: template_path,
+        merge_strategy: merge_strategy,
+        section_type: :schema,
+      }
+    end
+    def merge_data(target, source, strategy, window_attr, template_path)
+      case strategy
+      when 'deep'
+        deep_merge(target, source)
+      when 'shallow'
+        shallow_merge(target, source, window_attr, template_path)
+      when 'strict'
+        strict_merge(target, source, window_attr, template_path)
+      else
+        raise ArgumentError, "Unknown merge strategy: #{strategy}"
+      end
+    end
+    def deep_merge(target, source)
+      result = target.dup
+      source.each do |key, value|
+        result[key] = if result.key?(key) && result[key].is_a?(Hash) && value.is_a?(Hash)
+          deep_merge(result[key], value)
+        else
+          value
+                      end
+      end
+      result
+    end
+    def shallow_merge(target, source, window_attr, template_path)
+      result = target.dup
+      source.each do |key, value|
+        if result.key?(key)
+          raise ::Rhales::HydrationCollisionError.new(
+            "#{window_attr}.#{key}",
+            @window_attributes[window_attr][:path],
+            template_path,
+          )
+        end
+        result[key] = value
+      end
+      result
+    end
+    def strict_merge(target, source, window_attr, template_path)
+      # In strict mode, any collision is an error
+      target.each_key do |key|
+        next unless source.key?(key)
+        raise ::Rhales::HydrationCollisionError.new(
+          "#{window_attr}.#{key}",
+          @window_attributes[window_attr][:path],
+          template_path,
+        )
+      end
+      target.merge(source)
+    end
+    def build_template_path_for_schema(parser)
+      schema_node = parser.section_node('schema')
+      line_number = schema_node ? schema_node.location.start_line : 1
+      if parser.file_path
+        "#{parser.file_path}:#{line_number}"
+      else
+        "<inline>:#{line_number}"
+      end
+    end
+    # Check if data is considered empty for collision detection
+    def empty_data?(data)
+      return true if data.nil?
+      return true if data == {}
+      return true if data == []
+      return true if data.respond_to?(:empty?) && data.empty?
+      false
+    end
+    # Extract expected keys using hybrid approach
+    #
+    # Tries to load pre-generated JSON schema first (reliable, handles all Zod patterns).
+    # Falls back to regex parsing for development (before schemas are generated).
+    #
+    # To generate JSON schemas, run: rake rhales:schema:generate
+    def extract_expected_keys(template_name, schema_content)
+      # Try JSON schema first (reliable, comprehensive)
+      keys = extract_keys_from_json_schema(template_name)
+      if keys&.any?
+        log_with_metadata(Rhales.logger, :debug, 'Schema keys extracted from JSON schema',
+          template: template_name, key_count: keys.size, method: 'json_schema'
+        )
+        return keys
+      end
+      # Fall back to regex (development, before schemas generated)
+      keys = extract_keys_from_zod_regex(schema_content)
+      if keys.any?
+        log_with_metadata(Rhales.logger, :debug, 'Schema keys extracted from Zod regex',
+          template: template_name, key_count: keys.size, method: 'regex_fallback',
+          note: 'Run rake rhales:schema:generate for reliable validation'
+        )
+      end
+      keys
+    end
+    # Extract keys from pre-generated JSON schema (preferred method)
+    def extract_keys_from_json_schema(template_name)
+      schema = load_schema_cached(template_name)
+      return nil unless schema
+      # Extract all properties from JSON schema
+      properties = schema.dig('properties') || {}
+      properties.keys
+    rescue StandardError => ex
+      log_with_metadata(Rhales.logger, :debug, 'JSON schema loading failed',
+        template: template_name, error: ex.message
+      )
+      nil
+    end
+    # Load and cache JSON schema from disk
+    def load_schema_cached(template_name)
+      @schema_cache[template_name] ||= begin
+        schema_path = File.join(@schemas_dir, "#{template_name}.json")
+        return nil unless File.exist?(schema_path)
+        JSON.parse(File.read(schema_path))
+      rescue JSON::ParserError, Errno::ENOENT => ex
+        log_with_metadata(Rhales.logger, :debug, 'Schema file error',
+          template: template_name, path: schema_path, error: ex.class.name
+        )
+        nil
+      end
+    end
+    # Extract keys from Zod schema using regex (fallback method)
+    #
+    # NOTE: This is a basic implementation that only matches simple patterns like:
+    #   fieldName: z.string()
+    #
+    # It will miss:
+    # - Nested object literals: settings: { theme: z.enum([...]) }
+    # - Complex compositions and unions
+    # - Multiline definitions
+    #
+    # For reliable validation, generate JSON schemas with: rake rhales:schema:generate
+    def extract_keys_from_zod_regex(schema_content)
+      return [] unless schema_content
+      keys = []
+      schema_content.scan(/(\w+):\s*z\./) do |match|
+        keys << match[0]
+      end
+      keys
+    rescue StandardError => ex
+      log_with_metadata(Rhales.logger, :debug, 'Regex key extraction failed',
+        error: ex.message,
+        schema_preview: schema_content[0..100]
+      )
+      []
+    end
+  end
+end