inquirex 0.5.0 → 0.6.0

data/lib/inquirex/definition.rb

@@ -13,7 +13,14 @@ module Inquirex
   # @attr_reader start_step_id [Symbol] id of the first step in the flow
   # @attr_reader steps [Hash<Symbol, Node>] frozen map of step id => node
   class Definition
-    attr_reader :id, :version, :meta, :start_step_id, :steps, :accumulators
+    attr_reader :id,
+      :version,
+      :meta,
+      :start_step_id,
+      :steps,
+      :accumulators,
+      :actions,
+      :allowed_domains
 
     # @param start_step_id [Symbol] id of the initial step
     # @param nodes [Hash<Symbol, Node>] all steps keyed by id
@@ -21,14 +28,20 @@ module Inquirex
     # @param version [String] semver
     # @param meta [Hash] frontend metadata
     # @param accumulators [Hash<Symbol, Accumulator>] named running totals
+    # @param actions [Array<Actions::Action>] post-completion actions, in order
+    # @param allowed_domains [Array<String>] hosts outbound effects (webhook)
+    #   may send answers to; "example.com" exact, "*.example.com" subdomains
     # @raise [Errors::DefinitionError] if start_step_id is not present in nodes
-    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {}, accumulators: {})
+    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {},
+      accumulators: {}, actions: [], allowed_domains: [])
       @id = id
       @version = version
       @meta = meta.freeze
       @start_step_id = start_step_id.to_sym
       @steps = nodes.freeze
       @accumulators = accumulators.freeze
+      @actions = actions.freeze
+      @allowed_domains = normalize_domains(allowed_domains)
       validate!
       freeze
     end
@@ -50,6 +63,25 @@ module Inquirex
       @steps.keys
     end
 
+    # Whether a host is covered by the allowed_domains declaration.
+    # "example.com" matches that host exactly; "*.example.com" matches any
+    # subdomain but not the apex. Matching is case-insensitive; an empty
+    # allowlist allows nothing.
+    #
+    # @example With allowed_domains ["*.example.com"]
+    #   definition.allowed_host?("api.example.com") # => true
+    #   definition.allowed_host?("API.EXAMPLE.COM") # => true (case-insensitive)
+    #   definition.allowed_host?("example.com")     # => false (wildcard excludes the apex)
+    #
+    # @param host [String]
+    # @return [Boolean]
+    def allowed_host?(host)
+      target = host.to_s.downcase
+      @allowed_domains.any? do |entry|
+        entry.start_with?("*.") ? target.end_with?(entry[1..]) : target == entry
+      end
+    end
+
     # Serializes the definition to a JSON string.
     # Lambdas (default procs, compute blocks) are silently stripped.
     #
@@ -66,6 +98,7 @@ module Inquirex
       hash["id"] = @id if @id
       hash["version"] = @version
       hash["meta"] = @meta unless @meta.empty?
+      hash["allowed_domains"] = @allowed_domains unless @allowed_domains.empty?
       hash["start"] = @start_step_id.to_s
       unless @accumulators.empty?
         hash["accumulators"] = @accumulators.each_with_object({}) do |(name, acc), h|
@@ -73,6 +106,8 @@ module Inquirex
         end
       end
       hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
+      serializable_actions = @actions.select(&:serializable?)
+      hash["actions"] = serializable_actions.map(&:to_h) unless serializable_actions.empty?
       hash
     end
 
@@ -97,6 +132,8 @@ module Inquirex
       start = hash["start"] || hash[:start]
       steps_data = hash["steps"] || hash[:steps] || {}
       acc_data = hash["accumulators"] || hash[:accumulators] || {}
+      actions_data = hash["actions"] || hash[:actions] || []
+      domains = hash["allowed_domains"] || hash[:allowed_domains] || []
 
       nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
         sym_id = step_id.to_sym
@@ -108,15 +145,40 @@ module Inquirex
         h[sym] = Accumulator.from_h(sym, entry)
       end
 
-      new(start_step_id: start, nodes:, id:, version:, meta:, accumulators:)
+      actions = actions_data.map { |entry| Actions::Action.from_h(entry) }
+
+      new(start_step_id: start,
+        nodes:,
+        id:,
+        version:,
+        meta:,
+        accumulators:,
+        actions:,
+        allowed_domains: domains)
     end
 
     private
 
     def validate!
-      return if @steps.key?(@start_step_id)
+      unless @steps.key?(@start_step_id)
+        raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
+      end
 
-      raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
+      @actions.each do |action|
+        action.effects.each { |effect| effect.validate_against(self) }
+      end
+    end
+
+    def normalize_domains(domains)
+      domains.map do |entry|
+        domain = entry.to_s.strip.downcase
+        if domain.empty? || domain == "*" || domain.match?(%r{[/\s:@]})
+          raise Errors::DefinitionError,
+            "allowed_domains entries must be bare domains like \"example.com\" " \
+            "or \"*.example.com\", got #{entry.inspect}"
+        end
+        domain
+      end.freeze
     end
   end
 end

data/lib/inquirex/dsl/action_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Builds an Actions::Action from an `action` DSL block. Every effect verb
+    # registered in Inquirex::Actions (send_email, plus anything host gems
+    # register) is available as a method automatically; `run` wraps arbitrary
+    # Ruby in an Actions::Custom effect.
+    #
+    #   action :admin_alert do
+    #     send_email to: "admin@example.com", subject: "New lead: {{name}}",
+    #                html: "{{answers_summary}}"
+    #     run { |answers, outbox| Metrics.count(:lead, answers.to_flat_h) }
+    #   end
+    class ActionBuilder
+      def initialize
+        @effects = []
+      end
+
+      # Escape hatch: arbitrary server-side Ruby. Stripped from JSON.
+      #
+      # @yield [answers, outbox]
+      def run(&block)
+        raise Errors::DefinitionError, "run requires a block" unless block
+
+        @effects << Actions::Custom.new(block)
+      end
+
+      # Registered effect verbs (send_email, ...) resolve dynamically so that
+      # newly registered effect types become DSL words without core changes.
+      def method_missing(name, *args, **params, &)
+        return super unless Actions.registered?(name)
+
+        raise Errors::DefinitionError, "#{name} takes keyword arguments only" unless args.empty?
+
+        @effects << Actions.lookup(name).new(**params)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        Actions.registered?(name) || super
+      end
+
+      # @param id [Symbol]
+      # @param rule [Rules::Base, nil]
+      # @return [Actions::Action]
+      def build(id, rule: nil)
+        raise Errors::DefinitionError, "action #{id.inspect} declares no effects" if @effects.empty?
+
+        Actions::Action.new(id:, effects: @effects, rule:)
+      end
+    end
+  end
+end

data/lib/inquirex/dsl/flow_builder.rb

@@ -16,6 +16,18 @@ module Inquirex
         @nodes = {}
         @meta = {}
         @accumulators = {}
+        @actions = []
+        @allowed_domains = []
+      end
+
+      # Declares the domains outbound effects (webhook) may send answers to.
+      # Conventionally the first declaration in a definition, so the flow's
+      # egress surface is auditable at a glance. "example.com" matches that
+      # host exactly; "*.example.com" matches its subdomains.
+      #
+      # @param domains [Array<String>]
+      def allowed_domains(*domains)
+        @allowed_domains.concat(domains.flatten)
       end
 
       # Declares a named running total the flow accumulates into as answers come in.
@@ -104,6 +116,35 @@ module Inquirex
         add_step(id, :confirm, &)
       end
 
+      # Declares a named post-completion action: effects (send_email, run, ...)
+      # executed server-side after the flow finishes, with the collected
+      # answers. Runs in declaration order; gate with a serializable rule via
+      # the if: option.
+      #
+      # @example Email the collected answers when business income was selected
+      #   action :notify_sales, if: Rules::Contains.new(:income_types, "Business") do
+      #     send_email to: "sales@example.com",
+      #                subject: "New lead: {{name}}",
+      #                html: "{{answers_summary}}"
+      #   end
+      #
+      # @param id [Symbol] action identifier
+      # @param opts [Hash] only if: is recognized — a Rules::Base gate
+      # @yield block evaluated in ActionBuilder (send_email, run, ...)
+      def action(id, **opts, &block)
+        rule = opts.delete(:if)
+        raise Errors::DefinitionError, "Unknown action options: #{opts.keys.inspect}" unless opts.empty?
+
+        sym = id.to_sym
+        if @actions.any? { |a| a.id == sym }
+          raise Errors::DefinitionError, "Duplicate action id: #{sym.inspect}"
+        end
+
+        builder = ActionBuilder.new
+        builder.instance_eval(&block) if block
+        @actions << builder.build(sym, rule:)
+      end
+
       # Produces the frozen Definition.
       #
       # @return [Definition]
@@ -113,12 +154,14 @@ module Inquirex
         raise Errors::DefinitionError, "No steps defined" if @nodes.empty?
 
         Definition.new(
-          start_step_id: @start_step_id,
-          nodes:         @nodes,
-          id:            @flow_id,
-          version:       @flow_version,
-          meta:          @meta,
-          accumulators:  @accumulators
+          start_step_id:   @start_step_id,
+          nodes:           @nodes,
+          id:              @flow_id,
+          version:         @flow_version,
+          meta:            @meta,
+          accumulators:    @accumulators,
+          actions:         @actions,
+          allowed_domains: @allowed_domains
         )
       end
 

data/lib/inquirex/engine/state_serializer.rb

@@ -5,11 +5,13 @@ module Inquirex
     # Handles state serialization for Engine persistence (DB, session store, etc.).
     # Normalizes string-keyed hashes (from JSON round-trips) to symbol-keyed hashes.
     module StateSerializer
+      # Per-key normalizers applied by .symbolize_state; unlisted keys pass through unchanged.
       SYMBOLIZERS = {
-        current_step_id: ->(v) { v&.to_sym },
-        history:         ->(v) { Array(v).map { |e| e&.to_sym } },
-        answers:         ->(v) { symbolize_answers(v) },
-        totals:          ->(v) { symbolize_answers(v) }
+        current_step_id:     ->(v) { v&.to_sym },
+        history:             ->(v) { Array(v).map { |e| e&.to_sym } },
+        answers:             ->(v) { symbolize_answers(v) },
+        totals:              ->(v) { symbolize_answers(v) },
+        completion_metadata: ->(v) { symbolize_answers(v) }
       }.freeze
 
       # Normalizes a state hash so step ids and history entries are symbols.

data/lib/inquirex/engine.rb

@@ -12,6 +12,23 @@ module Inquirex
   class Engine
     attr_reader :definition, :answers, :history, :current_step_id, :totals
 
+    # Metadata describing how and where the flow was completed. Rendering
+    # front-ends (TTY, web, chat widget) attach a rich version from an
+    # after_completion hook; when no hook provides one, the engine stamps a
+    # minimal core version the moment the flow finishes. Only :engine and
+    # :engine_version are required members; everything else is free-form.
+    #
+    # @return [CompletionMetadata, nil] nil until the flow finishes
+    attr_accessor :completion_metadata
+
+    # Exceptions raised by after_completion hooks, in the order they were
+    # raised. Hooks are isolated from one another, so a raising hook is
+    # recorded here rather than propagated — callers that care can inspect
+    # this after the flow finishes. Empty when every hook succeeded.
+    #
+    # @return [Array<StandardError>]
+    attr_reader :completion_hook_errors
+
     # @param definition [Definition] the flow to run
     # @param validator [Validation::Adapter] optional (default: NullAdapter)
     def initialize(definition, validator: Validation::NullAdapter.new)
@@ -21,6 +38,9 @@ module Inquirex
       @current_step_id = definition.start_step_id
       @validator = validator
       @totals = init_totals
+      @completion_metadata = nil
+      @after_completion_hooks = []
+      @completion_hook_errors = []
       @history << @current_step_id
       skip_display_steps_if_needed
     end
@@ -101,18 +121,62 @@ module Inquirex
       @answers
     end
 
+    # Registers a hook to run when the flow finishes. The block receives the
+    # engine; front-ends typically use it to attach a rich
+    # completion_metadata (host, user, ips, terminal, ...). Optional — after
+    # all hooks run, the engine fills in a minimal CompletionMetadata when
+    # none of them provided one. Registering on an already-finished engine
+    # invokes the block immediately.
+    #
+    # Any number of hooks may be registered; they run in registration order.
+    # Each is isolated from the others — a hook that raises a StandardError
+    # has it recorded in #completion_hook_errors, and the remaining hooks
+    # still run. Non-StandardError exceptions (Interrupt, SignalException)
+    # propagate, as they should.
+    #
+    # @example Stamp renderer-specific completion metadata
+    #   engine.after_completion do |eng|
+    #     eng.completion_metadata = Inquirex::CompletionMetadata.new(
+    #       engine: "inquirex-tty", engine_version: "0.5.0", hostname: Socket.gethostname
+    #     )
+    #   end
+    #
+    # @yield [Engine] the engine, at completion time
+    # @return [Engine] self
+    def after_completion(&block)
+      raise ArgumentError, "after_completion requires a block" unless block
+
+      @after_completion_hooks << block
+      if finished?
+        invoke_completion_hook(block)
+        ensure_completion_metadata
+      end
+      self
+    end
+
     # Serializable state snapshot for persistence or resumption.
     #
     # @return [Hash]
     def to_state
       {
-        current_step_id: @current_step_id,
-        answers:         @answers,
-        history:         @history,
-        totals:          @totals
+        current_step_id:     @current_step_id,
+        answers:             @answers,
+        history:             @history,
+        totals:              @totals,
+        completion_metadata: @completion_metadata&.to_h
       }
     end
 
+    # The collected answers with the completion metadata (when a renderer
+    # attached one) merged in under the :completion_metadata key.
+    #
+    # @return [Hash]
+    def answers_with_metadata
+      return @answers if @completion_metadata.nil?
+
+      @answers.merge(completion_metadata: @completion_metadata.to_h)
+    end
+
     # Rebuilds an Engine from a previously saved state.
     #
     # @param definition [Definition] same definition used when state was captured
@@ -135,6 +199,9 @@ module Inquirex
       @answers = state[:answers] || {}
       @history = state[:history] || []
       @totals = state[:totals] || init_totals
+      @completion_metadata = CompletionMetadata.from_h(state[:completion_metadata])
+      @after_completion_hooks = []
+      @completion_hook_errors = []
     end
 
     def init_totals
@@ -154,12 +221,37 @@ module Inquirex
       node = @definition.step(@current_step_id)
       next_id = node.next_step_id(@answers)
       @current_step_id = next_id
-      return unless next_id
+      return run_after_completion_hooks unless next_id
 
       @history << next_id
       skip_if_needed
     end
 
+    # Fires the moment the flow finishes: runs registered after_completion
+    # hooks in registration order, then guarantees completion_metadata exists
+    # — hooks may attach a rich version; absent that (including when the hook
+    # meant to supply it raised), a minimal core-stamped one is used.
+    def run_after_completion_hooks
+      @after_completion_hooks.each { |hook| invoke_completion_hook(hook) }
+      ensure_completion_metadata
+      nil
+    end
+
+    # Runs one hook in isolation. A StandardError is recorded rather than
+    # propagated so that one misbehaving hook cannot silently cancel the
+    # hooks registered after it, nor abort the completion of the flow itself.
+    def invoke_completion_hook(hook)
+      hook.call(self)
+    rescue StandardError => e
+      @completion_hook_errors << e
+    end
+
+    def ensure_completion_metadata
+      return if @completion_metadata
+
+      @completion_metadata = CompletionMetadata.new(engine: "inquirex", engine_version: VERSION)
+    end
+
     # Auto-skips the current step if its skip_if rule is satisfied.
     def skip_if_needed
       return if finished?

data/lib/inquirex/errors.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Inquirex
+  # Namespace for all Inquirex exception classes.
   module Errors
     # Base exception for all Inquirex errors.
     class Error < StandardError; end
@@ -26,5 +27,9 @@ module Inquirex
 
     # Raised when serializing or deserializing a Definition to/from JSON fails.
     class SerializationError < Error; end
+
+    # Raised when a post-completion action cannot execute structurally,
+    # e.g. send_email is used without the mail gem installed.
+    class ActionError < Error; end
   end
 end

data/lib/inquirex/graph/mermaid_exporter.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 module Inquirex
+  # Namespace for flow graph export utilities (Mermaid, ...).
   module Graph
     # Exports a flow Definition to Mermaid flowchart syntax for visualization.
     # Node labels show verb + truncated question/text; edges show condition labels.
     class MermaidExporter
+      # Maximum characters of a node label before it is truncated with "...".
       MAX_LABEL_LENGTH = 50
 
       attr_reader :definition

data/lib/inquirex/node.rb

@@ -27,7 +27,9 @@ module Inquirex
   class Node
     # Valid DSL verbs and which ones collect input from the user.
     VERBS = %i[ask say header btw warning confirm].freeze
+    # Verbs that collect input from the user.
     COLLECTING_VERBS = %i[ask confirm].freeze
+    # Verbs that only display content and auto-advance.
     DISPLAY_VERBS = %i[say header btw warning].freeze
 
     # Valid data types for :ask steps.

data/lib/inquirex/rules/all.rb

@@ -1,29 +1,41 @@
 # frozen_string_literal: true
 
 module Inquirex
+  # Namespace for rule AST nodes used in transitions and visibility conditions.
   module Rules
     # Composite rule: logical AND of multiple sub-rules. All must be true.
     class All < Base
       attr_reader :rules
 
+      # @param rules [Array<Rules::Base>] sub-rules that must all hold
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # True when every sub-rule evaluates true (vacuously true when empty).
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         @rules.all? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [Hash{String => Object}] wire format with nested rule hashes
       def to_h
         { "op" => "all", "rules" => @rules.map(&:to_h) }
       end
 
+      # @return [String] human-readable form, sub-rules joined with AND
       def to_s
         "(#{@rules.join(" AND ")})"
       end
 
+      # Deserializes an All rule, recursively rehydrating its sub-rules.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [All]
       def self.from_h(hash)
         raw_rules = hash["rules"] || hash[:rules] || []
         new(*raw_rules.map { |r| Base.from_h(r) })

data/lib/inquirex/rules/any.rb

@@ -6,24 +6,35 @@ module Inquirex
     class Any < Base
       attr_reader :rules
 
+      # @param rules [Array<Rules::Base>] sub-rules, at least one of which must hold
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # True when at least one sub-rule evaluates true (false when empty).
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         @rules.any? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [Hash{String => Object}] wire format with nested rule hashes
       def to_h
         { "op" => "any", "rules" => @rules.map(&:to_h) }
       end
 
+      # @return [String] human-readable form, sub-rules joined with OR
       def to_s
         "(#{@rules.join(" OR ")})"
       end
 
+      # Deserializes an Any rule, recursively rehydrating its sub-rules.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [Any]
       def self.from_h(hash)
         raw_rules = hash["rules"] || hash[:rules] || []
         new(*raw_rules.map { |r| Base.from_h(r) })

data/lib/inquirex/rules/base.rb

@@ -30,6 +30,12 @@ module Inquirex
 
       # Deserializes a rule from a plain Hash (e.g. parsed from JSON).
       #
+      # @example Rehydrate a rule from its wire format
+      #   rule = Inquirex::Rules::Base.from_h(
+      #     "op" => "equals", "field" => "filing_status", "value" => "single"
+      #   )
+      #   rule.evaluate(filing_status: "single") # => true
+      #
       # @param hash [Hash] rule hash with string or symbol keys
       # @return [Rules::Base] the deserialized rule
       # @raise [Inquirex::Errors::SerializationError] on unknown operator

data/lib/inquirex/rules/contains.rb

@@ -7,6 +7,8 @@ module Inquirex
     class Contains < Base
       attr_reader :field, :value
 
+      # @param field [Symbol, String] step id whose answer is inspected
+      # @param value [Object] value the answer must include
       def initialize(field, value)
         super()
         @field = field.to_sym
@@ -14,18 +16,28 @@ module Inquirex
         freeze
       end
 
+      # True when the field's answer, coerced to an Array, includes the value.
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         Array(answers[@field]).include?(@value)
       end
 
+      # @return [Hash{String => Object}] wire format, same shape .from_h accepts
       def to_h
         { "op" => "contains", "field" => @field.to_s, "value" => @value }
       end
 
+      # @return [String] human-readable form, e.g. "Business in income_types"
       def to_s
         "#{@value} in #{@field}"
       end
 
+      # Deserializes a Contains rule from a plain Hash.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [Contains]
       def self.from_h(hash)
         field = hash["field"] || hash[:field]
         value = hash["value"] || hash[:value]

data/lib/inquirex/rules/equals.rb

@@ -6,6 +6,8 @@ module Inquirex
     class Equals < Base
       attr_reader :field, :value
 
+      # @param field [Symbol, String] step id whose answer is compared
+      # @param value [Object] value the answer must equal
       def initialize(field, value)
         super()
         @field = field.to_sym
@@ -13,18 +15,28 @@ module Inquirex
         freeze
       end
 
+      # True when the field's answer equals the value (Ruby ==).
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         answers[@field] == @value
       end
 
+      # @return [Hash{String => Object}] wire format, same shape .from_h accepts
       def to_h
         { "op" => "equals", "field" => @field.to_s, "value" => @value }
       end
 
+      # @return [String] human-readable form, e.g. "filing_status == single"
       def to_s
         "#{@field} == #{@value}"
       end
 
+      # Deserializes an Equals rule from a plain Hash.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [Equals]
       def self.from_h(hash)
         field = hash["field"] || hash[:field]
         value = hash["value"] || hash[:value]

data/lib/inquirex/rules/greater_than.rb

@@ -6,6 +6,8 @@ module Inquirex
     class GreaterThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol, String] step id whose answer is compared
+      # @param value [Integer] threshold the answer must exceed
       def initialize(field, value)
         super()
         @field = field.to_sym
@@ -13,18 +15,28 @@ module Inquirex
         freeze
       end
 
+      # True when the field's answer, coerced to an Integer, exceeds the threshold.
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         answers[@field].to_i > @value
       end
 
+      # @return [Hash{String => Object}] wire format, same shape .from_h accepts
       def to_h
         { "op" => "greater_than", "field" => @field.to_s, "value" => @value }
       end
 
+      # @return [String] human-readable form, e.g. "dependents > 2"
       def to_s
         "#{@field} > #{@value}"
       end
 
+      # Deserializes a GreaterThan rule from a plain Hash.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [GreaterThan]
       def self.from_h(hash)
         field = hash["field"] || hash[:field]
         value = (hash["value"] || hash[:value]).to_i