inquirex 0.5.0 → 0.6.0

data/lib/inquirex/actions/send_email.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Declarative email effect. Builds a Mail::Message (the object ActionMailer
+    # itself wraps) from {{field}} templates and appends it to the outbox.
+    # Nothing is delivered — the host application sends the messages.
+    #
+    # Scalar fields (to, from, cc, bcc, reply_to, subject) and the text body
+    # render values verbatim; the html body HTML-escapes every interpolated
+    # value automatically. Both bodies given => multipart/alternative.
+    #
+    # 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.
+    #
+    # Images: reference external URLs in the html body. Attachments are
+    # deliberately unsupported.
+    #
+    # The mail gem is a soft dependency, required only when a message is
+    # actually built. Rails hosts always have it (ActionMailer depends on it).
+    class SendEmail < Base
+      # 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, :html
+
+      # @return [Hash{String => String}] extra headers (values support {{field}})
+      attr_reader :headers
+
+      # @param to [String] recipient template (required)
+      # @param subject [String] subject template (required)
+      # @param text [String, Hash, nil] plain-text body template or { file: }
+      # @param html [String, Hash, nil] HTML body template or { file: }
+      # @param headers [Hash] extra headers (values support {{field}})
+      # @raise [Errors::DefinitionError] when required fields are missing
+      def initialize(to:, subject:, from: nil, cc: nil, bcc: nil, reply_to: nil,
+        text: nil, html: nil, headers: {})
+        super()
+        @to = to
+        @from = from
+        @cc = cc
+        @bcc = bcc
+        @reply_to = reply_to
+        @subject = subject
+        @text = resolve_body(text)
+        @html = resolve_body(html)
+        @headers = headers.transform_keys(&:to_s).freeze
+        validate!
+        freeze
+      end
+
+      # Builds the message and appends it to the outbox.
+      #
+      # @param answers [Answers] completed answers
+      # @param outbox [Outbox] receives the built Mail::Message
+      # @return [void]
+      def call(answers, outbox)
+        outbox.add_message(to_mail(answers))
+      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.
+      #
+      # @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 = { "type" => "send_email" }
+        SCALAR_FIELDS.each do |field|
+          value = public_send(field)
+          hash[field.to_s] = value if value
+        end
+        hash["text"] = @text if @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] }
+        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),
+          html:     fetch.call(:html),
+          headers:  fetch.call(:headers) || {}
+        )
+      end
+
+      private
+
+      def attach_bodies(mail, answers)
+        text = @text && Template.render_text(@text, 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? && @html.nil?
+
+        raise Errors::DefinitionError, "send_email requires a 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::ActionError,
+          "send_email requires the mail gem — add `gem \"mail\"` to your Gemfile " \
+          "(Rails applications already have it via ActionMailer)"
+      end
+    end
+
+    register(:send_email, SendEmail)
+  end
+end

data/lib/inquirex/actions/template.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Inquirex
+  module Actions
+    # Renders {{field}} placeholders against collected answers.
+    #
+    # Placeholders are dot-notation keys resolved via Answers#to_flat_h
+    # ("{{email}}", "{{business.count}}"). The syntax is deliberately inert —
+    # no code execution — so flow definitions stored in a database can be
+    # rendered server-side safely and a visual editor can preview templates
+    # client-side. It matches the {{field}} placeholder convention used by
+    # inquirex-llm prompts.
+    #
+    # Rendering modes:
+    # - render_text — values inserted verbatim
+    # - render_html — every interpolated value is HTML-escaped
+    #
+    # The built-in {{answers_summary}} placeholder expands to all collected
+    # answers: "key: value" lines in text mode, a simple table in HTML mode.
+    # Unknown fields render as empty strings; array values join with ", ".
+    module Template
+      # Matches one {{field}} placeholder; capture 1 is the dot-notation key.
+      PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/
+      # Reserved placeholder key that expands to a summary of all collected answers.
+      SUMMARY_KEY = "answers_summary"
+
+      module_function
+
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @return [String]
+      def render_text(string, answers)
+        render(string, answers, html: false)
+      end
+
+      # @example Interpolated values are HTML-escaped
+      #   answers = Inquirex::Answers.new(name: "Bob & Sons")
+      #   Inquirex::Actions::Template.render_html("<p>{{name}}</p>", answers)
+      #   # => "<p>Bob &amp; Sons</p>"
+      #
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @return [String]
+      def render_html(string, answers)
+        render(string, answers, html: true)
+      end
+
+      # Shared implementation behind render_text and render_html.
+      #
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @param html [Boolean] whether to HTML-escape interpolated values
+      # @return [String]
+      def render(string, answers, html:)
+        flat = answers.to_flat_h
+        string.gsub(PLACEHOLDER) do
+          key = Regexp.last_match(1)
+          next(html ? summary_html(flat) : summary_text(flat)) if key == SUMMARY_KEY
+
+          value = format_value(flat[key])
+          html ? CGI.escapeHTML(value) : value
+        end
+      end
+
+      # Formats a single answer value for interpolation.
+      #
+      # @param value [Object] raw answer value (nil renders as "")
+      # @return [String] arrays joined with ", ", everything else via #to_s
+      def format_value(value)
+        value.is_a?(Array) ? value.join(", ") : value.to_s
+      end
+
+      # Expands {{answers_summary}} in text mode.
+      #
+      # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+      # @return [String] one "key: value" line per answer
+      def summary_text(flat)
+        flat.map { |key, value| "#{key}: #{format_value(value)}" }.join("\n")
+      end
+
+      # Expands {{answers_summary}} in HTML mode.
+      #
+      # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+      # @return [String] a simple HTML table with one row per answer, fully escaped
+      def summary_html(flat)
+        rows = flat.map do |key, value|
+          "<tr><th>#{CGI.escapeHTML(key)}</th><td>#{CGI.escapeHTML(format_value(value))}</td></tr>"
+        end
+        %(<table class="inquirex-answers">#{rows.join}</table>)
+      end
+    end
+  end
+end

data/lib/inquirex/actions/webhook.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Inquirex
+  module Actions
+    # Declarative webhook effect: POSTs the completed answers as a JSON
+    # envelope ({"answers" => {...}}) to a statically-declared URL.
+    #
+    # Security posture — the URL must be auditable and its host covered by the
+    # definition's allowed_domains declaration:
+    #
+    # - the URL is a literal string; {{field}} templates are rejected so the
+    #   destination host can never depend on user input
+    # - https only; plain http is permitted solely for localhost development
+    # - userinfo (https://user@host/) is rejected
+    # - redirects are not followed (Net::HTTP does not follow them)
+    # - the host check runs in Definition#validate!, which every definition
+    #   passes through — including JSON-rehydrated ones, so a tampered URL
+    #   fails at load time, before anything executes
+    #
+    # A non-2xx response raises Errors::ActionError, which the Runner records
+    # as a :failed result without blocking other actions.
+    class Webhook < Base
+      # Default open/read timeout in seconds for the webhook POST.
+      DEFAULT_TIMEOUT = 10
+      # Hosts for which plain http is tolerated (local development only).
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+
+      attr_reader :url, :headers, :timeout
+
+      # @param url [String] literal https URL (no {{field}} templates)
+      # @param headers [Hash] extra request headers (literal values)
+      # @param timeout [Integer] open/read timeout in seconds
+      def initialize(url:, headers: {}, timeout: DEFAULT_TIMEOUT)
+        super()
+        @url = url.to_s
+        @headers = headers.transform_keys(&:to_s).transform_values(&:to_s).freeze
+        @timeout = timeout.to_i
+        @uri = parse_and_check!(@url)
+        freeze
+      end
+
+      # @return [String] lowercase host of the webhook URL
+      def host = @uri.host.downcase
+
+      # POSTs the answers envelope to the declared URL.
+      #
+      # @param answers [Answers] completed answers
+      # @param _outbox [Outbox] unused — webhooks build no messages
+      # @return [Net::HTTPResponse] the 2xx response
+      # @raise [Errors::ActionError] when the endpoint responds non-2xx
+      def call(answers, _outbox)
+        require "net/http"
+        response = post(answers)
+        code = response.code.to_i
+        return response if (200..299).cover?(code)
+
+        raise Errors::ActionError, "webhook #{host} responded with HTTP #{response.code}"
+      end
+
+      # Enforced from Definition#validate!.
+      #
+      # @param definition [Definition] owning definition, source of allowed_domains
+      # @return [void]
+      # @raise [Errors::DefinitionError] when the host is not allowlisted
+      def validate_against(definition)
+        return if definition.allowed_host?(host)
+
+        raise Errors::DefinitionError,
+          "webhook url host #{host.inspect} is not covered by allowed_domains " \
+          "#{definition.allowed_domains.inspect} — declare it at the top of the definition"
+      end
+
+      # @return [Hash] wire format, same shape .from_h accepts
+      def to_h
+        hash = { "type" => "webhook", "url" => @url }
+        hash["headers"] = @headers unless @headers.empty?
+        hash["timeout"] = @timeout unless @timeout == DEFAULT_TIMEOUT
+        hash
+      end
+
+      # @param hash [Hash] string or symbol keys
+      # @return [Webhook]
+      def self.from_h(hash)
+        fetch = ->(key) { hash[key.to_s] || hash[key.to_sym] }
+        new(
+          url:     fetch.call(:url),
+          headers: fetch.call(:headers) || {},
+          timeout: fetch.call(:timeout) || DEFAULT_TIMEOUT
+        )
+      end
+
+      private
+
+      def post(answers)
+        request = Net::HTTP::Post.new(@uri)
+        request["Content-Type"] = "application/json"
+        @headers.each { |name, value| request[name] = value }
+        request.body = JSON.generate("answers" => answers.to_h)
+
+        Net::HTTP.start(
+          @uri.host,
+          @uri.port,
+          use_ssl:      @uri.scheme == "https",
+          open_timeout: @timeout,
+          read_timeout: @timeout
+        ) { |http| http.request(request) }
+      end
+
+      def parse_and_check!(url)
+        if url.include?("{{")
+          raise Errors::DefinitionError,
+            "webhook url does not support {{field}} templates — the destination must be static"
+        end
+
+        uri = parse(url)
+        raise Errors::DefinitionError, "webhook url must be http(s): #{url.inspect}" unless uri.is_a?(URI::HTTP)
+        raise Errors::DefinitionError, "webhook url must include a host: #{url.inspect}" if uri.host.to_s.empty?
+        raise Errors::DefinitionError, "webhook url must not include userinfo: #{url.inspect}" if uri.userinfo
+
+        if uri.scheme == "http" && !LOCAL_HOSTS.include?(uri.host.downcase)
+          raise Errors::DefinitionError,
+            "webhook url must use https (plain http is allowed only for localhost): #{url.inspect}"
+        end
+
+        uri
+      end
+
+      def parse(url)
+        URI.parse(url)
+      rescue URI::InvalidURIError => e
+        raise Errors::DefinitionError, "webhook url is not a valid URL: #{e.message}"
+      end
+    end
+
+    register(:webhook, Webhook)
+  end
+end

data/lib/inquirex/actions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Post-completion actions: named side-effect declarations that run
+  # server-side after a flow finishes, with access to the collected answers.
+  #
+  # The DSL word `action` groups one or more *effects* (send_email, run, ...).
+  # Effects are looked up in a registry keyed by their DSL verb, so new effect
+  # types — a webhook, a save_record in inquirex-rails — plug in without core
+  # changes: register the class and it gains both the DSL word and JSON wire
+  # support.
+  #
+  #   Inquirex::Actions.register(:webhook, MyGem::WebhookEffect)
+  #
+  # Actions never deliver anything themselves. send_email builds Mail::Message
+  # objects into Answers#outbox; the host application decides how to send them.
+  module Actions
+    @registry = {}
+
+    class << self
+      # Registers an effect class under a DSL verb name.
+      #
+      # @param type [Symbol] DSL verb (e.g. :send_email)
+      # @param klass [Class] an Actions::Base subclass
+      def register(type, klass)
+        @registry[type.to_sym] = klass
+      end
+
+      # @param type [Symbol, String]
+      # @return [Boolean]
+      def registered?(type)
+        @registry.key?(type.to_sym)
+      end
+
+      # @param type [Symbol, String]
+      # @return [Class]
+      # @raise [Errors::SerializationError] for unknown effect types
+      def lookup(type)
+        @registry.fetch(type.to_sym) do
+          raise Errors::SerializationError, "Unknown action effect type: #{type.inspect}"
+        end
+      end
+
+      # @return [Array<Symbol>] registered effect verbs
+      def types = @registry.keys
+
+      # Runs all of the definition's actions against the given answers.
+      #
+      # @param definition [Definition]
+      # @param answers [Answers, Hash]
+      # @return [Answers] with #outbox populated
+      def run(definition, answers)
+        Runner.new(definition).call(answers)
+      end
+    end
+  end
+end

data/lib/inquirex/answers.rb

@@ -84,10 +84,22 @@ module Inquirex
     end
 
     # Number of top-level answer keys.
+    #
+    # @return [Integer]
     def size
       @data.size
     end
 
+    # Mail::Message objects (and result trail) built by post-completion
+    # actions. Deliberately excluded from #to_h, #to_flat_h, #to_json and
+    # #== — the outbox rides alongside the answer data, never inside it.
+    # Delivery is the host application's responsibility.
+    #
+    # @return [Actions::Outbox]
+    def outbox
+      @outbox ||= Actions::Outbox.new
+    end
+
     # Merge another hash or Answers into this one (returns new Answers instance).
     #
     # @param other [Hash, Answers]
@@ -97,6 +109,7 @@ module Inquirex
       Answers.new(@data.merge(other_data))
     end
 
+    # @return [String] debug representation including the underlying hash
     def inspect
       "#<Inquirex::Answers #{@data.inspect}>"
     end

data/lib/inquirex/completion_metadata.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require "json"
+
+module Inquirex
+  # An OpenStruct describing how a flow reached completion: which rendering
+  # engine collected the answers, and any environment details that renderer
+  # chose to attach (host uname, user, IP addresses, terminal, ...).
+  #
+  # Only :engine and :engine_version are required members — enforced at
+  # construction. Everything else is free-form OpenStruct behavior: unset
+  # members read as nil, assignment creates members, nested OpenStructs
+  # (e.g. uname) are welcome.
+  #
+  # @example
+  #   meta = Inquirex::CompletionMetadata.new(
+  #     engine: "inquirex-tty", engine_version: "0.5.0",
+  #     uname: OpenStruct.new(Etc.uname)
+  #   )
+  #   meta.engine          # => "inquirex-tty"
+  #   meta.uname.machine   # => "arm64"
+  #   meta.hostname        # => nil (unset members read as nil)
+  #   meta.to_h            # => plain nested Hash, JSON-ready
+  class CompletionMetadata < OpenStruct
+    # Members that must be provided at construction; everything else is optional.
+    REQUIRED_MEMBERS = %i[engine engine_version].freeze
+
+    # Exists solely to make :engine and :engine_version required keywords —
+    # OpenStruct itself would accept anything.
+    #
+    # @param engine [String] rendering front-end name (e.g. "inquirex-tty")
+    # @param engine_version [String] rendering front-end version
+    # @param extra [Hash] any additional, optional members
+    def initialize(engine:, engine_version:, **extra) # rubocop:disable Lint/UselessMethodDefinition
+      super
+    end
+
+    # Rebuilds an instance from a hash (e.g. persisted engine state after a
+    # JSON round-trip). Keys may be strings or symbols; nested hashes come
+    # back as OpenStructs so dot-access survives the round-trip.
+    #
+    # @param hash [Hash, nil]
+    # @return [CompletionMetadata, nil] nil when hash is nil or empty
+    # @raise [ArgumentError] when :engine or :engine_version is missing
+    def self.from_h(hash)
+      return nil if hash.nil? || hash.empty?
+
+      members = hash.to_h { |k, v| [k.to_sym, v.is_a?(Hash) ? OpenStruct.new(v) : v] }
+      new(**members)
+    end
+
+    # OpenStruct#to_h is shallow; deep-convert nested OpenStructs (uname et
+    # al.) so state serialization and JSON output stay plain data.
+    #
+    # @return [Hash]
+    def to_h
+      deep_plain(super)
+    end
+
+    # @return [String] JSON representation
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+
+    # @return [String] debug representation of the deep-plain member hash
+    def inspect
+      "#<Inquirex::CompletionMetadata #{to_h.inspect}>"
+    end
+
+    private
+
+    def deep_plain(value)
+      case value
+      when OpenStruct then deep_plain(value.to_h)
+      when Hash       then value.transform_values { |v| deep_plain(v) }
+      when Array      then value.map { |v| deep_plain(v) }
+      else value
+      end
+    end
+  end
+end