inquirex 0.7.0 → 0.9.4

data/lib/inquirex/safe_source/vocabulary.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module SafeSource
+    # The registry of DSL words {Validator} accepts, and of the words it
+    # deliberately refuses.
+    #
+    # Every entry is *bound to the builder that implements it*: the six flow
+    # verbs are derived from {Node::VERBS}, step types from {Node::TYPES}, the
+    # rule vocabulary from {DSL::RuleHelpers}, and each scope declares the
+    # method list it governs (`vocabulary:`) so that {.undeclared_names} can
+    # name any builder method nobody has made an allowlist decision about.
+    # `spec/inquirex/safe_source/vocabulary_spec.rb` fails the build when that
+    # list is non-empty — which is what stops this table drifting away from the
+    # DSL it is supposed to describe.
+    #
+    # Downstream gems extend the vocabulary at boot rather than forking it.
+    #
+    # @example Teaching the allowlist about inquirex-llm's verbs
+    #   V = Inquirex::SafeSource::Vocabulary
+    #   V.register_scope(:llm_step, label: "an LLM step",
+    #     vocabulary: -> { Inquirex::LLM::DSL::StepBuilder.public_instance_methods(false) })
+    #   V.allow(:flow, :clarify, positional: %i[symbol], block: :llm_step)
+    #   V.allow(:llm_step, :prompt, positional: %i[literal])
+    #   V.exclude(:llm_step, :fallback, "a Ruby block cannot be validated")
+    module Vocabulary
+      # The only constant a flow definition may name.
+      ENTRY_CONSTANT = :Inquirex
+
+      # The only method that constant may receive.
+      ENTRY_METHOD = :define
+
+      # Keyword-descriptor key standing for "every keyword not named
+      # explicitly". Legitimate only where the real method takes `**rest`.
+      ANY_OTHER = :*
+
+      # Value kinds a `transition` accepts. Shared by every step-like scope.
+      TRANSITION_KEYWORDS = { to: :symbol, if_rule: :rule, requires_server: :literal }.freeze
+
+      # The `send_email` fields, and the shape each accepts. One definition
+      # serves both DSL forms — the flow-level keywords (`send_email to: ...`)
+      # and the block setters (`send_email do to "..." end`) — so the two can
+      # never drift apart. `headers` is `:literal` because it is a Hash; every
+      # other field is one static string.
+      EMAIL_FIELD_KEYWORDS = {
+        to:            :string,
+        from:          :string,
+        cc:            :string,
+        bcc:           :string,
+        reply_to:      :string,
+        subject:       :string,
+        text:          :string,
+        markdown_text: :string,
+        html:          :string,
+        headers:       :literal
+      }.freeze
+
+      # Builder methods that exist for the builder's own sake and are not DSL
+      # words, so they need no allowlist decision. `params` is
+      # SendEmailBuilder's accumulator, read by FlowBuilder once the block has
+      # run — nothing a flow author writes.
+      PLUMBING = %i[build params method_missing respond_to_missing?].freeze
+
+      class << self
+        # Declares a nested scope (idempotent): a block whose statements are
+        # validated against their own table of calls.
+        #
+        # @param name [Symbol] scope name, e.g. :step
+        # @param label [String] how to name the scope in a violation message,
+        #   article included ("a step")
+        # @param vocabulary [Proc, nil] returns the DSL words the scope's
+        #   builder really implements; used by {.undeclared_names} to detect
+        #   drift. Lazy, so load order does not matter.
+        # @return [void]
+        def register_scope(name, label:, vocabulary: nil)
+          sym = name.to_sym
+          @labels[sym] = label
+          @vocabularies[sym] = vocabulary
+          @calls[sym] ||= {}
+          @exclusions[sym] ||= {}
+        end
+
+        # Allowlists one call inside one scope.
+        #
+        # @param scope [Symbol] scope name, e.g. :step
+        # @param name [Symbol] DSL word, e.g. :question
+        # @param positional [Array<Symbol>, Hash] see {CallSpec#positional}
+        # @param keywords [nil, Hash] see {CallSpec#keywords}
+        # @param block [Symbol] :forbidden, or the scope its block opens
+        # @return [CallSpec] the registered spec
+        # @raise [ArgumentError] when the scope was never registered
+        def allow(scope, name, positional: [], keywords: nil, block: :forbidden)
+          table = @calls.fetch(scope.to_sym) { raise ArgumentError, "Unknown SafeSource scope: #{scope.inspect}" }
+          table[name.to_sym] = CallSpec.new(positional:, keywords:, block:)
+        end
+
+        # Records a DSL word that is knowingly *not* allowlisted, with the
+        # reason — which {Validator} quotes back to the author, so a rejection
+        # reads as a decision rather than an oversight.
+        #
+        # @param scope [Symbol] scope name
+        # @param name [Symbol] DSL word, e.g. :compute
+        # @param reason [String] why safe mode cannot accept it
+        # @return [String] the reason
+        # @raise [ArgumentError] when the scope was never registered
+        def exclude(scope, name, reason)
+          table = @exclusions.fetch(scope.to_sym) { raise ArgumentError, "Unknown SafeSource scope: #{scope.inspect}" }
+          table[name.to_sym] = reason
+        end
+
+        # @param scope [Symbol]
+        # @param name [Symbol]
+        # @return [CallSpec, nil] nil when the call is not allowlisted
+        def spec_for(scope, name)
+          @calls.fetch(scope.to_sym, {})[name.to_sym]
+        end
+
+        # @param scope [Symbol]
+        # @param name [Symbol]
+        # @return [String, nil] why the call is excluded, nil when it was never
+        #   part of the scope's vocabulary at all
+        def exclusion_for(scope, name)
+          @exclusions.fetch(scope.to_sym, {})[name.to_sym]
+        end
+
+        # @param scope [Symbol]
+        # @return [String] the scope's human-readable label, article included
+        def label_for(scope)
+          @labels.fetch(scope.to_sym, "an unknown")
+        end
+
+        # @param name [Symbol]
+        # @return [Boolean] whether the scope has been registered
+        def scope?(name)
+          @labels.key?(name.to_sym)
+        end
+
+        # @return [Array<Symbol>] every registered scope
+        def scopes
+          @labels.keys
+        end
+
+        # @param scope [Symbol]
+        # @return [Array<Symbol>] every allowlisted call in the scope
+        def allowed_names(scope)
+          @calls.fetch(scope.to_sym, {}).keys
+        end
+
+        # @param scope [Symbol]
+        # @return [Array<Symbol>] every knowingly excluded call in the scope
+        def excluded_names(scope)
+          @exclusions.fetch(scope.to_sym, {}).keys
+        end
+
+        # The DSL words the scope's builder implements, per the `vocabulary:`
+        # binding given to {.register_scope}, minus builder plumbing.
+        #
+        # @param scope [Symbol]
+        # @return [Array<Symbol>] empty when the scope declared no binding
+        def governed_names(scope)
+          @vocabularies.fetch(scope.to_sym, nil)&.call.to_a.map(&:to_sym) - PLUMBING
+        end
+
+        # Builder methods with no allowlist decision: neither allowed nor
+        # knowingly excluded. Anything here is a new DSL word that silently
+        # became unusable in safe mode (or, worse, an old one that quietly
+        # gained a new meaning).
+        #
+        # @example Fail fast at boot
+        #   raise "unreviewed DSL words" if V.scopes.any? { |s| V.undeclared_names(s).any? }
+        #
+        # @param scope [Symbol]
+        # @return [Array<Symbol>]
+        def undeclared_names(scope)
+          governed_names(scope) - allowed_names(scope) - excluded_names(scope)
+        end
+
+        # Allowlist entries that no longer correspond to a real builder method
+        # — a typo, or a DSL word that has since been removed or renamed.
+        #
+        # @param scope [Symbol]
+        # @return [Array<Symbol>]
+        def stale_names(scope)
+          return [] if @vocabularies.fetch(scope.to_sym, nil).nil?
+
+          (allowed_names(scope) + excluded_names(scope)) - governed_names(scope)
+        end
+
+        # The spec for `Inquirex.define` itself.
+        #
+        # @return [CallSpec]
+        def entry_spec
+          CallSpec.new(positional: [], keywords: { id: :string, version: :string }, block: :flow)
+        end
+
+        # Discards every registration and reinstalls the core vocabulary.
+        # Hosts call this to undo an extension; the specs call it to isolate.
+        #
+        # @return [void]
+        def reset!
+          @labels = {}
+          @calls = {}
+          @exclusions = {}
+          @vocabularies = {}
+          install_core!
+        end
+
+        private
+
+        # @return [void]
+        def install_core!
+          register_scope(:rule,
+            label:      "a rule",
+            vocabulary: -> { DSL::RuleHelpers.public_instance_methods(false) })
+          register_scope(:flow,
+            label:      "a flow",
+            vocabulary: -> { DSL::FlowBuilder.public_instance_methods(false) })
+          register_scope(:step,
+            label:      "a step",
+            vocabulary: -> { DSL::StepBuilder.public_instance_methods(false) })
+          register_scope(:email,
+            label:      "a send_email",
+            vocabulary: -> { DSL::SendEmailBuilder.public_instance_methods(false) })
+
+          install_rules!
+          install_flow!
+          install_step!
+          install_email!
+        end
+
+        # Rules are serializable AST objects, so their arguments are always a
+        # field name plus a literal — never an expression, which is what makes
+        # `equals(:a, ENV["X"])` a violation.
+        #
+        # @return [void]
+        def install_rules!
+          %i[equals contains greater_than less_than].each do |name|
+            allow :rule, name, positional: %i[symbol literal]
+          end
+          allow :rule, :not_empty, positional: %i[symbol]
+          %i[all any].each { |name| allow :rule, name, positional: { repeat: :rule, min: 1 } }
+        end
+
+        # @return [void]
+        def install_flow!
+          allow :flow, :start, positional: %i[symbol]
+          allow :flow,
+            :meta,
+            keywords: { title: :literal, subtitle: :literal, brand: :literal, theme: :literal }
+          allow :flow,
+            :accumulator,
+            positional: %i[symbol],
+            keywords:   { type: :type_name, default: :literal }
+          Node::VERBS.each { |verb| allow :flow, verb, positional: %i[symbol], block: :step }
+          # `send_email` takes an optional `if:` rule gate plus, in its inline
+          # form, the same field keywords the block setters cover. Both shapes
+          # are real DSL (`send_email to: "...", subject: "..."` and
+          # `send_email do to "..." end`), so both are described here; block
+          # values win at build time either way.
+          allow :flow,
+            :send_email,
+            keywords: EMAIL_FIELD_KEYWORDS.merge(if: :rule),
+            block:    { optional: :email }
+        end
+
+        # @return [void]
+        def install_step!
+          allow :step, :type, positional: %i[type_name]
+          allow :step, :question, positional: %i[string]
+          allow :step, :text, positional: %i[string]
+          allow :step, :options, positional: %i[literal]
+          allow :step, :default, positional: %i[literal]
+          # `required` is inert metadata: Node coerces it with `value ? true :
+          # false` and serializes it as `"required": false`. It reaches nothing
+          # outside the definition, and an author who can write the DSL text can
+          # already delete the question outright — strictly more powerful than
+          # marking it skippable — so it is allowed rather than excluded.
+          # `{ optional: :literal }` mirrors `required(value = true)`: both bare
+          # `required` and `required false` are real DSL.
+          allow :step, :required, positional: { optional: :literal }
+          allow :step, :skip_if, positional: %i[rule]
+          allow :step, :transition, keywords: TRANSITION_KEYWORDS
+          allow :step,
+            :accumulate,
+            positional: %i[symbol],
+            keywords:   { lookup: :literal, per_selection: :literal, per_unit: :literal, flat: :literal }
+          # widget(type:, target:, **opts) and price(**kwargs) really do take
+          # open keyword lists — a widget's options and a price lookup's option
+          # keys are arbitrary — so ANY_OTHER is faithful rather than lax.
+          allow :step, :widget, keywords: { type: :symbol, target: :symbol, ANY_OTHER => :literal }
+          allow :step,
+            :price,
+            keywords: { lookup: :literal, per_selection: :literal, per_unit: :literal,
+                        flat: :literal, ANY_OTHER => :literal }
+          exclude :step, :compute, "a compute block is arbitrary Ruby, indistinguishable from a payload"
+        end
+
+        # The `send_email` setters take one static string each (`headers` a
+        # literal Hash). {SendEmail} never delivers anything and the gem never
+        # renders a body, so what a stored definition can express here is a
+        # template the *host* chooses to act on — which is why the verb needs
+        # no exclusions. `{{field}}` placeholders are ordinary text to the
+        # parser; the shape enforced is "a string literal with no Ruby in it",
+        # so `#{}`, a constant and a method call are rejected exactly as
+        # everywhere else.
+        #
+        # The `{ file: "path" }` body form is not expressible: bodies are
+        # `:string`, so a stored flow cannot make the gem `File.read` an
+        # attacker-chosen path at definition time.
+        #
+        # @return [void]
+        def install_email!
+          EMAIL_FIELD_KEYWORDS.each do |setter, shape|
+            allow :email, setter, positional: [shape]
+          end
+        end
+      end
+
+      reset!
+    end
+  end
+end

data/lib/inquirex/safe_source.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "safe_source/call_spec"
+require_relative "safe_source/vocabulary"
+require_relative "safe_source/validator"
+
+module Inquirex
+  # Decides whether a string of flow DSL is safe to evaluate — *without*
+  # evaluating it.
+  #
+  # {Inquirex.load_dsl} is an `eval`. Whenever the text comes from somewhere
+  # other than your own repository — a database column a customer edits, an
+  # upload, an LLM, a visual builder's "sync" button — evaluating it unguarded
+  # is arbitrary code execution in the process that loads the flow. As of 0.9.2
+  # `load_dsl` therefore runs {SafeSource.validate!} first, and only source that
+  # matches the real DSL vocabulary ({Vocabulary}) with literal arguments gets
+  # past it.
+  #
+  # Use {.validate} or {.safe?} directly to audit stored definitions without
+  # loading them — the answer is "would `load_dsl` accept this?", which is
+  # exactly what you want before a deploy tightens the allowlist.
+  #
+  # @example Reject before evaluating
+  #   Inquirex.load_dsl(customer.flow_dsl)          # validates, then evals
+  #   Inquirex.load_dsl(File.read("flow.rb"), unsafe: true)  # your own file: skip validation
+  #
+  # @example Audit a table of stored definitions
+  #   Qualifier.find_each do |q|
+  #     violations = Inquirex::SafeSource.validate(q.flow_dsl)
+  #     puts "REJECT #{q.id}: #{violations.join("; ")}" if violations.any?
+  #   end
+  #
+  # @example Raise the ceilings for an unusually large questionnaire
+  #   Inquirex::SafeSource.max_source_bytes = 256 * 1024
+  #   Inquirex::SafeSource.max_depth = 32
+  module SafeSource
+    # Default ceiling on DSL source size, in bytes.
+    #
+    # Real flows are tiny: the largest definition anywhere in this project or
+    # its downstream app — a 47-step loan application with three levels of
+    # composed rules — is under 6 KB. 64 KiB is an order of magnitude above
+    # that, comfortably fits a several-hundred-step questionnaire, and still
+    # bounds the work handed to Prism (and to any formatter the host runs on
+    # the same text), neither of which should be fed megabytes of hostile input.
+    DEFAULT_MAX_SOURCE_BYTES = 64 * 1024
+
+    # Default ceiling on AST nesting depth.
+    #
+    # Measured against every flow in this gem's specs and examples and the
+    # downstream app's fixtures, the deepest legitimate construct needs 9 levels
+    # (`define` → block → `ask` → block → `transition` → `all` → `any` →
+    # `equals` → literal). 24 leaves better than 2.5x headroom while keeping
+    # the validator's own recursion clear of a stack overflow triggered by
+    # `all(all(all(...)))` nested a million deep.
+    DEFAULT_MAX_DEPTH = 24
+
+    @max_source_bytes = DEFAULT_MAX_SOURCE_BYTES
+    @max_depth = DEFAULT_MAX_DEPTH
+
+    class << self
+      # Ceiling on DSL source size in bytes, applied by {.validate} and
+      # therefore by {Inquirex.load_dsl}.
+      #
+      # @return [Integer]
+      attr_accessor :max_source_bytes
+
+      # Ceiling on AST nesting depth, applied by {.validate} and therefore by
+      # {Inquirex.load_dsl}.
+      #
+      # @return [Integer]
+      attr_accessor :max_depth
+
+      # Every reason the source would be rejected. An empty array means the
+      # source is inside the allowlist — it says nothing about whether the flow
+      # is semantically valid (unknown step reference, missing `start`), which
+      # only evaluation can decide.
+      #
+      # @param source [String, nil] Inquirex DSL source
+      # @param max_bytes [Integer] override the size ceiling for this call
+      # @param max_depth [Integer] override the depth ceiling for this call
+      # @return [Array<String>] `"line N: reason"` messages, empty when safe
+      def validate(source, max_bytes: max_source_bytes, max_depth: self.max_depth)
+        Validator.new(source, max_bytes:, max_depth:).violations
+      end
+
+      # @param source [String, nil] Inquirex DSL source
+      # @param max_bytes [Integer] override the size ceiling for this call
+      # @param max_depth [Integer] override the depth ceiling for this call
+      # @return [Boolean] true when the source is inside the allowlist
+      def safe?(source, max_bytes: max_source_bytes, max_depth: self.max_depth)
+        validate(source, max_bytes:, max_depth:).empty?
+      end
+
+      # Validates, and raises unless the source is inside the allowlist.
+      #
+      # @param source [String, nil] Inquirex DSL source
+      # @param max_bytes [Integer] override the size ceiling for this call
+      # @param max_depth [Integer] override the depth ceiling for this call
+      # @return [String] the source, unchanged, when it is safe
+      # @raise [Errors::UnsafeSourceError] listing every violation found
+      def validate!(source, max_bytes: max_source_bytes, max_depth: self.max_depth)
+        violations = validate(source, max_bytes:, max_depth:)
+        raise Errors::UnsafeSourceError, violations unless violations.empty?
+
+        source
+      end
+    end
+  end
+end

data/lib/inquirex/send_email.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # A declarative email built from the collected answers, declared at flow
+  # level with the DSL verb `send_email`. This is the only server-side
+  # completion declaration the core gem carries — anything richer (webhooks,
+  # CRM pushes, custom code) belongs to the host application.
+  #
+  #   send_email if: not_empty(:email) do
+  #     to      "{{email}}"
+  #     from    "forms@agentica.group"
+  #     subject "Thanks {{name}} — we got your inquiry"
+  #     markdown_text <<~TEXT
+  #       Hi {{name}},
+  #
+  #       We received your answers and will reply within one business day.
+  #
+  #       {{answers_summary}}
+  #     TEXT
+  #   end
+  #
+  # Nothing is ever delivered by this gem. A SendEmail is data: templated
+  # header fields plus one or more body templates, serialized into the
+  # definition JSON under "send_emails". The host application decides when
+  # (and whether) to render and deliver — either from the serialized fields
+  # directly, or via #to_mail, which builds a Mail::Message (the object
+  # ActionMailer wraps).
+  #
+  # Scalar fields (to, from, cc, bcc, reply_to, subject) and the text /
+  # markdown_text bodies render {{field}} values verbatim; the html body
+  # HTML-escapes every interpolated value automatically. markdown_text is
+  # carried on the wire as markdown — the core gem never renders Markdown
+  # to HTML (no dependencies); hosts that want an HTML part render it
+  # themselves.
+  #
+  # Bodies accept an inline template String or { file: "path" }, which is
+  # read once at definition time and inlined — a definition rehydrated from
+  # JSON never touches the filesystem.
+  #
+  # The mail gem is a soft dependency, required only when #to_mail is
+  # called. Rails hosts always have it (ActionMailer depends on it).
+  class SendEmail
+    # Scalar header fields rendered verbatim via Template.render_text in #to_mail and #to_h.
+    SCALAR_FIELDS = %i[to from cc bcc reply_to subject].freeze
+
+    # @return [String] required recipient / subject templates ({{field}} placeholders allowed)
+    attr_reader :to, :subject
+
+    # @return [String, nil] optional address templates ({{field}} placeholders allowed)
+    attr_reader :from, :cc, :bcc, :reply_to
+
+    # @return [String, nil] body template, inlined at definition time when { file: } was given
+    attr_reader :text, :markdown_text, :html
+
+    # @return [Hash{String => String}] extra headers (values support {{field}})
+    attr_reader :headers
+
+    # @return [Rules::Base, nil] gate — the email applies only when the rule is true
+    attr_reader :rule
+
+    # @param to [String] recipient template (required; keyword defaults to nil
+    #   so a missing field raises the friendly DefinitionError from #validate!)
+    # @param subject [String] subject template (required)
+    # @param text [String, Hash, nil] plain-text body template or { file: }
+    # @param markdown_text [String, Hash, nil] Markdown body template or { file: }
+    # @param html [String, Hash, nil] HTML body template or { file: }
+    # @param headers [Hash] extra headers (values support {{field}})
+    # @param rule [Rules::Base, nil] serializable gate (the DSL's if: option)
+    # @raise [Errors::DefinitionError] when required fields are missing
+    def initialize(to: nil, subject: nil, from: nil, cc: nil, bcc: nil, reply_to: nil,
+      text: nil, markdown_text: nil, html: nil, headers: {}, rule: nil)
+      @to = to
+      @from = from
+      @cc = cc
+      @bcc = bcc
+      @reply_to = reply_to
+      @subject = subject
+      @text = resolve_body(text)
+      @markdown_text = resolve_body(markdown_text)
+      @html = resolve_body(html)
+      @headers = headers.transform_keys(&:to_s).freeze
+      @rule = rule
+      validate!
+      freeze
+    end
+
+    # Whether this email should be built for the given answers — true when
+    # no gate was declared or the gate rule evaluates to true.
+    #
+    # @param answers_hash [Hash] step_id => value context for rule evaluation
+    # @return [Boolean]
+    def applicable?(answers_hash)
+      @rule.nil? || @rule.evaluate(answers_hash)
+    end
+
+    # Builds a Mail::Message from the templates and the given answers.
+    # Pure function — safe to call from a background job to rebuild
+    # messages from persisted answers. The text part is @text, falling back
+    # to @markdown_text rendered verbatim (Markdown reads fine as plain
+    # text); the html part is @html when present.
+    #
+    # @param answers [Answers]
+    # @return [Mail::Message]
+    def to_mail(answers)
+      require_mail!
+      mail = ::Mail.new
+      SCALAR_FIELDS.each do |field|
+        value = public_send(field)
+        mail.public_send(:"#{field}=", Template.render_text(value, answers)) if value
+      end
+      @headers.each { |name, value| mail.header[name] = Template.render_text(value.to_s, answers) }
+      attach_bodies(mail, answers)
+      mail
+    end
+
+    # @return [Hash] wire format, same shape .from_h accepts
+    def to_h
+      hash = {}
+      hash["if"] = @rule.to_h if @rule
+      SCALAR_FIELDS.each do |field|
+        value = public_send(field)
+        hash[field.to_s] = value if value
+      end
+      hash["text"] = @text if @text
+      hash["markdown_text"] = @markdown_text if @markdown_text
+      hash["html"] = @html if @html
+      hash["headers"] = @headers unless @headers.empty?
+      hash
+    end
+
+    # @param hash [Hash] string or symbol keys
+    # @return [SendEmail]
+    def self.from_h(hash)
+      fetch = ->(key) { hash[key.to_s] || hash[key.to_sym] }
+      rule_data = fetch.call(:if)
+      new(
+        to:            fetch.call(:to),
+        from:          fetch.call(:from),
+        cc:            fetch.call(:cc),
+        bcc:           fetch.call(:bcc),
+        reply_to:      fetch.call(:reply_to),
+        subject:       fetch.call(:subject),
+        text:          fetch.call(:text),
+        markdown_text: fetch.call(:markdown_text),
+        html:          fetch.call(:html),
+        headers:       fetch.call(:headers) || {},
+        rule:          rule_data ? Rules::Base.from_h(rule_data) : nil
+      )
+    end
+
+    private
+
+    def attach_bodies(mail, answers)
+      text_source = @text || @markdown_text
+      text = text_source && Template.render_text(text_source, answers)
+      html = @html && Template.render_html(@html, answers)
+      if text && html
+        mail.text_part = build_part("text/plain; charset=UTF-8", text)
+        mail.html_part = build_part("text/html; charset=UTF-8", html)
+      elsif html
+        mail.content_type = "text/html; charset=UTF-8"
+        mail.body = html
+      else
+        mail.body = text
+      end
+    end
+
+    def build_part(content_type, body)
+      part = ::Mail::Part.new
+      part.content_type = content_type
+      part.body = body
+      part
+    end
+
+    # Inline template string, or { file: "path" } read once at definition time.
+    def resolve_body(value)
+      return value if value.nil? || value.is_a?(String)
+
+      path = value.is_a?(Hash) && (value[:file] || value["file"])
+      return File.read(File.expand_path(path)) if path.is_a?(String)
+
+      raise Errors::DefinitionError,
+        "send_email body must be a template String or { file: \"path\" }, got #{value.inspect}"
+    end
+
+    def validate!
+      raise Errors::DefinitionError, "send_email requires to:" if blank?(@to)
+      raise Errors::DefinitionError, "send_email requires subject:" if blank?(@subject)
+      return unless @text.nil? && @markdown_text.nil? && @html.nil?
+
+      raise Errors::DefinitionError, "send_email requires a text:, markdown_text: or html: body"
+    end
+
+    def blank?(value) = value.nil? || value.to_s.strip.empty?
+
+    def require_mail!
+      return if defined?(::Mail)
+
+      require "mail"
+    rescue LoadError
+      raise Errors::SendEmailError,
+        "send_email requires the mail gem — add `gem \"mail\"` to your Gemfile " \
+        "(Rails applications already have it via ActionMailer)"
+    end
+  end
+end