sxn 0.2.0

data/lib/sxn/templates/template_engine.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require_relative "template_processor"
+require_relative "template_variables"
+require_relative "template_security"
+require_relative "errors"
+require_relative "../runtime_validations"
+
+# Add support for hash deep merging if not available
+unless Hash.method_defined?(:deep_merge)
+  class Hash
+    def deep_merge(other_hash)
+      merge(other_hash) do |_key, oldval, newval|
+        if oldval.is_a?(Hash) && newval.is_a?(Hash)
+          oldval.deep_merge(newval)
+        else
+          newval
+        end
+      end
+    end
+  end
+end
+
+module Sxn
+  module Templates
+    # TemplateEngine is the main interface for template processing in sxn.
+    # It combines template processing, variable collection, and security validation
+    # to provide a safe and convenient API for generating files from templates.
+    #
+    # Features:
+    # - Built-in template discovery
+    # - Automatic variable collection
+    # - Security validation
+    # - Template caching
+    # - Multiple template formats support
+    #
+    # Example:
+    #   engine = TemplateEngine.new(session: session, project: project)
+    #   engine.process_template("rails/CLAUDE.md", "/path/to/output.md")
+    class TemplateEngine
+      # Built-in template directory
+      TEMPLATES_DIR = File.expand_path("../templates", __dir__)
+
+      def initialize(session: nil, project: nil, config: nil)
+        @session = session
+        @project = project
+        @config = config
+
+        @processor = TemplateProcessor.new
+        @variables_collector = TemplateVariables.new(session, project, config)
+        @security = TemplateSecurity.new
+        @template_cache = {}
+      end
+
+      # Process a template and write it to the specified destination
+      #
+      # @param template_name [String] Name/path of the template (e.g., "rails/CLAUDE.md")
+      # @param destination_path [String] Where to write the processed template
+      # @param custom_variables [Hash] Additional variables to merge
+      # @param options [Hash] Processing options
+      # @option options [Boolean] :force (false) Overwrite existing files
+      # @option options [Boolean] :validate (true) Validate template security
+      # @option options [String] :template_dir Custom template directory
+      # @return [String] Path to the created file
+      def process_template(template_name, destination_path, custom_variables = {}, options = {})
+        options = { force: false, validate: true, template_dir: nil }.merge(options)
+
+        # Find the template file
+        template_path = find_template(template_name, options[:template_dir])
+
+        # Check if destination exists and handle accordingly
+        destination = Pathname.new(destination_path)
+        if destination.exist? && !options[:force]
+          raise Errors::TemplateError,
+                "Destination file already exists: #{destination_path}. Use force: true to overwrite."
+        end
+
+        # steep:ignore:start - Template processing uses dynamic variable resolution
+        # Liquid template processing and variable collection use dynamic features
+        # that cannot be statically typed. Runtime validation provides safety.
+
+        # Collect variables
+        variables = collect_variables(custom_variables)
+
+        # Runtime validation of template variables
+        variables = RuntimeValidations.validate_template_variables(variables)
+
+        # Validate template security if requested
+        if options[:validate]
+          template_content = File.read(template_path)
+          @security.validate_template(template_content, variables)
+        end
+
+        # Process the template with runtime validation
+        result = @processor.process_file(template_path, variables, options)
+
+        # Create destination directory if it doesn't exist
+        destination.dirname.mkpath
+
+        # Write the result
+        destination.write(result)
+
+        destination_path
+      rescue Errors::TemplateSecurityError
+        # Re-raise security errors without wrapping
+        raise
+      rescue StandardError => e
+        raise Errors::TemplateProcessingError,
+              "Failed to process template '#{template_name}': #{e.message}"
+      end
+
+      # List available built-in templates
+      #
+      # @param category [String] Optional category filter (rails, javascript, common)
+      # @return [Array<String>] List of available template names
+      def list_templates(category = nil)
+        templates_dir = category ? File.join(TEMPLATES_DIR, category) : TEMPLATES_DIR
+        return [] unless Dir.exist?(templates_dir)
+
+        Dir.glob("**/*.liquid", base: templates_dir).map do |path|
+          category ? File.join(category, path) : path
+        end.sort
+      end
+
+      # Get template categories
+      #
+      # @return [Array<String>] List of template categories
+      def template_categories
+        return [] unless Dir.exist?(TEMPLATES_DIR)
+
+        Dir.entries(TEMPLATES_DIR)
+           .select { |entry| File.directory?(File.join(TEMPLATES_DIR, entry)) }
+           .reject { |entry| entry.start_with?(".") }
+           .sort
+      end
+
+      # Check if a template exists
+      #
+      # @param template_name [String] Name of the template to check
+      # @param template_dir [String] Optional custom template directory
+      # @return [Boolean] true if template exists
+      def template_exists?(template_name, template_dir = nil)
+        find_template(template_name, template_dir)
+        true
+      rescue Errors::TemplateNotFoundError
+        false
+      end
+
+      # Get template information
+      #
+      # @param template_name [String] Name of the template
+      # @param template_dir [String] Optional custom template directory
+      # @return [Hash] Template metadata
+      def template_info(template_name, template_dir = nil)
+        template_path = find_template(template_name, template_dir)
+        template_content = File.read(template_path)
+
+        {
+          name: template_name,
+          path: template_path,
+          size: template_content.bytesize,
+          variables: @processor.extract_variables(template_content),
+          syntax_valid: validate_template_syntax(template_content)
+        }
+      rescue StandardError => e
+        {
+          name: template_name,
+          error: e.message,
+          syntax_valid: false
+        }
+      end
+
+      # Validate template syntax without processing
+      #
+      # @param template_name [String] Name of the template
+      # @param template_dir [String] Optional custom template directory
+      # @return [Boolean] true if template syntax is valid
+      def validate_template_syntax(template_name, template_dir = nil)
+        # Better detection: if it contains Liquid syntax and no path separators, treat as content
+        if template_name.is_a?(String) &&
+           (template_name.include?("{{") || template_name.include?("{%")) &&
+           !template_name.include?("/") && !template_name.end_with?(".liquid")
+          # It's template content with Liquid syntax
+          template_content = template_name
+        elsif template_name.is_a?(String) && !template_name.include?("\n") &&
+              (template_name.include?("/") || template_name.match?(/\.\w+$/) || !template_name.include?("{{"))
+          # It's a template name/path
+          template_path = find_template(template_name, template_dir)
+          template_content = File.read(template_path)
+        else
+          # Default: treat as content for backward compatibility
+          template_content = template_name
+        end
+
+        @processor.validate_syntax(template_content)
+      rescue Errors::TemplateSyntaxError, Errors::TemplateNotFoundError
+        false
+      end
+
+      # Get available variables for templates
+      #
+      # @param custom_variables [Hash] Additional variables to include
+      # @return [Hash] All available variables
+      def available_variables(custom_variables = {})
+        collect_variables(custom_variables)
+      end
+
+      # Refresh variable cache (useful for long-running processes)
+      def refresh_variables!
+        @variables_collector.refresh!
+      end
+
+      # Clear template cache
+      def clear_cache!
+        @template_cache.clear
+        @security.clear_cache!
+      end
+
+      # Process a template string directly (not from file)
+      #
+      # @param template_content [String] The template content
+      # @param custom_variables [Hash] Variables to use
+      # @param options [Hash] Processing options
+      # @return [String] Processed template
+      def process_string(template_content, custom_variables = {}, options = {})
+        options = { validate: true }.merge(options)
+
+        variables = collect_variables(custom_variables)
+
+        @security.validate_template(template_content, variables) if options[:validate]
+
+        @processor.process(template_content, variables, options)
+      end
+
+      # Render a template with variables
+      #
+      # @param template_name [String] Name/path of the template
+      # @param variables [Hash] Variables to use for rendering
+      # @param options [Hash] Processing options
+      # @return [String] Rendered template content
+      def render_template(template_name, variables = {}, options = {})
+        # Find the template file
+        template_path = find_template(template_name, options[:template_dir])
+
+        # Read template content
+        template_content = File.read(template_path)
+
+        # Merge with available variables
+        all_variables = collect_variables(variables)
+
+        # Validate template security if requested
+        @security.validate_template(template_content, all_variables) if options.fetch(:validate, true)
+
+        # Process and return the result
+        @processor.process(template_content, all_variables, options)
+      rescue Errors::TemplateSecurityError
+        # Re-raise security errors without wrapping
+        raise
+      rescue StandardError => e
+        raise Errors::TemplateProcessingError,
+              "Failed to render template '#{template_name}': #{e.message}"
+      end
+
+      # Apply a set of templates to a directory
+      #
+      # @param template_set [String] Name of template set (rails, javascript, common)
+      # @param destination_dir [String] Directory to apply templates to
+      # @param custom_variables [Hash] Additional variables
+      # @param options [Hash] Processing options
+      # @return [Array<String>] List of created files
+      def apply_template_set(template_set, destination_dir, custom_variables = {}, options = {})
+        templates = list_templates(template_set)
+        created_files = []
+
+        templates.each do |template_name|
+          # Determine output filename (remove .liquid extension)
+          output_name = template_name.sub(/\.liquid$/, "")
+          output_path = File.join(destination_dir, File.basename(output_name))
+
+          begin
+            process_template(template_name, output_path, custom_variables, options)
+            created_files << output_path
+          rescue StandardError => e
+            # Log error but continue with other templates
+            warn "Failed to process template #{template_name}: #{e.message}"
+          end
+        end
+
+        created_files
+      end
+
+      private
+
+      # Find a template file by name
+      def find_template(template_name, custom_template_dir = nil)
+        # Remove .liquid extension if present for search
+        search_name = template_name.sub(/\.liquid$/, "")
+
+        # Search locations in order of preference
+        search_paths = []
+
+        # 1. Custom template directory if provided
+        if custom_template_dir
+          search_paths << File.join(custom_template_dir, "#{search_name}.liquid")
+          search_paths << File.join(custom_template_dir, search_name)
+        end
+
+        # 2. Built-in templates
+        search_paths << File.join(TEMPLATES_DIR, "#{search_name}.liquid")
+        search_paths << File.join(TEMPLATES_DIR, search_name)
+
+        # 3. Try with explicit .liquid extension
+        search_paths << File.join(TEMPLATES_DIR, template_name) if template_name.end_with?(".liquid")
+
+        # Find first existing template
+        found_path = search_paths.find { |path| File.exist?(path) }
+
+        unless found_path
+          available = list_templates.join(", ")
+          raise Errors::TemplateNotFoundError,
+                "Template '#{template_name}' not found. Available templates: #{available}"
+        end
+
+        found_path
+      end
+
+      # Collect all variables for template processing
+      def collect_variables(custom_variables = {})
+        # Get base variables from collector
+        base_variables = @variables_collector.collect
+
+        # Add sxn-specific variables
+        sxn_variables = {
+          sxn: {
+            version: Sxn::VERSION,
+            template_engine: "liquid",
+            generated_at: Time.now.iso8601
+          }
+        }
+
+        # Merge all variables (custom takes precedence)
+        base_variables.deep_merge(sxn_variables).deep_merge(custom_variables)
+      end
+    end
+  end
+end

data/lib/sxn/templates/template_processor.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "pathname"
+
+module Sxn
+  module Templates
+    # TemplateProcessor provides secure, sandboxed template processing using Liquid.
+    # It ensures that templates cannot execute arbitrary code or access the filesystem.
+    #
+    # Features:
+    # - Whitelisted variables only
+    # - No arbitrary code execution
+    # - Support for nested variable access (session.name, git.branch)
+    # - Built-in filters (upcase, downcase, join, etc.)
+    # - Template validation before processing
+    #
+    # Example:
+    #   processor = TemplateProcessor.new
+    #   variables = { session: { name: "test" }, git: { branch: "main" } }
+    #   result = processor.process("Hello {{session.name}} on {{git.branch}}", variables)
+    #   # => "Hello test on main"
+    class TemplateProcessor
+      # Maximum template size in bytes to prevent memory exhaustion
+      MAX_TEMPLATE_SIZE = 1_048_576 # 1MB
+
+      # Maximum rendering time in seconds to prevent infinite loops
+      MAX_RENDER_TIME = 10
+
+      # Allowed Liquid filters for security
+      ALLOWED_FILTERS = %w[
+        upcase downcase capitalize
+        strip lstrip rstrip
+        size length
+        first last
+        join split
+        sort sort_natural reverse
+        uniq compact
+        date
+        default
+        escape escape_once
+        truncate truncatewords
+        replace replace_first
+        remove remove_first
+        plus minus times divided_by modulo
+        abs ceil floor round
+        at_least at_most
+      ].freeze
+
+      def initialize
+        create_secure_liquid_environment
+      end
+
+      # Process a template string with the given variables
+      #
+      # @param template_content [String] The template content to process
+      # @param variables [Hash] Variables to make available in the template
+      # @param options [Hash] Processing options
+      # @option options [Boolean] :strict (true) Whether to raise on undefined variables
+      # @option options [Boolean] :validate (true) Whether to validate template syntax first
+      # @return [String] The processed template
+      # @raise [TemplateTooLargeError] if template exceeds size limit
+      # @raise [TemplateTimeoutError] if processing takes too long
+      # @raise [TemplateSecurityError] if template contains disallowed content
+      # @raise [TemplateSyntaxError] if template has invalid syntax
+      def process(template_content, variables = {}, options = {})
+        options = { strict: true, validate: true }.merge(options)
+
+        validate_template_size!(template_content)
+
+        # Sanitize and whitelist variables
+        sanitized_variables = sanitize_variables(variables)
+
+        # Parse template with syntax validation
+        template = parse_template(template_content, validate: options[:validate])
+
+        # Render with timeout protection
+        render_with_timeout(template, sanitized_variables, options)
+      rescue Liquid::SyntaxError => e
+        raise Errors::TemplateSyntaxError, "Template syntax error: #{e.message}"
+      rescue Errors::TemplateTooLargeError, Errors::TemplateTimeoutError, Errors::TemplateRenderError => e
+        # Re-raise specific template errors as-is
+        raise e
+      rescue StandardError => e
+        raise Errors::TemplateProcessingError, "Template processing failed: #{e.message}"
+      end
+
+      # Process a template file with the given variables
+      #
+      # @param template_path [String, Pathname] Path to the template file
+      # @param variables [Hash] Variables to make available in the template
+      # @param options [Hash] Processing options (see #process)
+      # @return [String] The processed template
+      # @raise [TemplateNotFoundError] if template file doesn't exist
+      def process_file(template_path, variables = {}, options = {})
+        template_path = Pathname.new(template_path)
+
+        raise Errors::TemplateNotFoundError, "Template file not found: #{template_path}" unless template_path.exist?
+
+        template_content = template_path.read
+        process(template_content, variables, options)
+      end
+
+      # Validate template syntax without processing
+      #
+      # @param template_content [String] The template content to validate
+      # @return [Boolean] true if template is valid
+      # @raise [TemplateSyntaxError] if template has invalid syntax
+      def validate_syntax(template_content)
+        validate_template_size!(template_content)
+        parse_template(template_content, validate: true)
+        true
+      rescue Liquid::SyntaxError => e
+        raise Errors::TemplateSyntaxError, "Template syntax error: #{e.message}"
+      end
+
+      # Extract variables referenced in a template
+      #
+      # @param template_content [String] The template content to analyze
+      # @return [Array<String>] List of variable names referenced in the template
+      def extract_variables(template_content)
+        variables = Set.new
+        loop_variables = Set.new
+
+        # Extract variables from {% if/unless variable %} expressions
+        template_content.scan(/\{%\s*(?:if|unless)\s+(\w+)(?:\.\w+)*.*?%\}/) do |match|
+          variables.add(match[0])
+        end
+
+        # Extract collection variables from {% for item in collection %} expressions
+        template_content.scan(/\{%\s*for\s+(\w+)\s+in\s+(\w+)(?:\.\w+)*.*?%\}/) do |loop_var, collection_var|
+          loop_variables.add(loop_var)
+          variables.add(collection_var)
+        end
+
+        # Extract variables from {{ variable }} expressions, excluding loop variables
+        # But only from outside control blocks
+        content_outside_blocks = template_content.dup
+
+        # Remove content inside control blocks to avoid extracting variables from inside conditionals
+        content_outside_blocks.gsub!(/\{%\s*if\s+.*?\{%\s*endif\s*%\}/m, "")
+        content_outside_blocks.gsub!(/\{%\s*unless\s+.*?\{%\s*endunless\s*%\}/m, "")
+        content_outside_blocks.gsub!(/\{%\s*for\s+.*?\{%\s*endfor\s*%\}/m, "")
+
+        content_outside_blocks.scan(/\{\{\s*(\w+)(?:\.\w+)*.*?\}\}/) do |match|
+          var_name = match[0]
+          variables.add(var_name) unless loop_variables.include?(var_name)
+        end
+
+        variables.to_a.sort
+      end
+
+      private
+
+      # Create a secure Liquid environment with restricted capabilities
+      def create_secure_liquid_environment
+        # Configure security globally for this processor
+        # Note: These settings affect global state, but we restore them in cleanup if needed
+
+        # Disable dangerous tags in global registry
+        Liquid::Template.tags.delete("include")
+        Liquid::Template.tags.delete("include_relative")
+        Liquid::Template.tags.delete("render")
+
+        true
+      end
+
+      # Validate template size to prevent memory exhaustion
+      def validate_template_size!(template_content)
+        size = template_content.bytesize
+        return if size <= MAX_TEMPLATE_SIZE
+
+        raise Errors::TemplateTooLargeError,
+              "Template size #{size} bytes exceeds limit of #{MAX_TEMPLATE_SIZE} bytes"
+      end
+
+      # Parse template and optionally validate syntax
+      def parse_template(template_content, validate: true)
+        if validate
+          # First pass: syntax validation only
+          Liquid::Template.parse(template_content, error_mode: :strict)
+        end
+
+        # Second pass: actual parsing for rendering
+        Liquid::Template.parse(template_content, error_mode: :strict)
+      end
+
+      # Sanitize and whitelist variables to prevent injection
+      def sanitize_variables(variables)
+        sanitized = {}
+
+        variables.each do |key, value|
+          sanitized_key = sanitize_key(key)
+          sanitized_value = sanitize_value(value)
+          sanitized[sanitized_key] = sanitized_value
+        end
+
+        sanitized
+      end
+
+      # Sanitize variable keys to ensure they're safe
+      def sanitize_key(key)
+        key.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+      end
+
+      # Recursively sanitize variable values
+      def sanitize_value(value)
+        case value
+        when Hash
+          value.transform_keys { |k| sanitize_key(k) }
+               .transform_values { |v| sanitize_value(v) }
+        when Array
+          value.map { |v| sanitize_value(v) }
+        when String
+          # Escape any potential HTML/JS in strings
+          value.gsub(%r{<script\b[^<]*(?:(?!</script>)<[^<]*)*</script>}mi, "")
+               .gsub(/<[^>]*>/, "")
+        when Symbol
+          value.to_s
+        when Numeric, TrueClass, FalseClass, NilClass
+          value
+        when Time, Date
+          value.iso8601
+        else
+          # Convert unknown types to string representation
+          value.to_s
+        end
+      end
+
+      # Render template with timeout protection
+      def render_with_timeout(template, variables, options)
+        start_time = Time.now
+
+        # Set up a thread to handle timeout
+        timeout_thread = Thread.new do
+          sleep(MAX_RENDER_TIME)
+          Thread.main.raise(Errors::TemplateTimeoutError,
+                            "Template rendering exceeded #{MAX_RENDER_TIME} seconds")
+        end
+
+        begin
+          # Create rendering context with security settings
+          # For Liquid 5.x, we need to use the Context object for strict control
+
+          # Create context with variables and options
+          context = Liquid::Context.new(
+            variables, # assigns
+            {}, # instance_assigns
+            {
+              strict_variables: options[:strict],
+              strict_filters: false
+            }
+          )
+
+          result = template.render(context)
+
+          # Check for rendering errors
+          if template.errors.any?
+            error_message = template.errors.join(", ")
+            raise Errors::TemplateRenderError, "Template rendering errors: #{error_message}"
+          end
+
+          result
+        ensure
+          timeout_thread.kill
+
+          # Log performance metrics in debug mode
+          if ENV["SXN_DEBUG"]
+            elapsed = Time.now - start_time
+            puts "Template rendered in #{elapsed.round(3)}s"
+          end
+        end
+      end
+
+      # Alias for validate_syntax to match expected interface
+      alias validate_template validate_syntax
+    end
+  end
+end