inquirex 0.5.0 → 0.6.1

data/lib/inquirex/engine.rb

@@ -12,6 +12,32 @@ 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
+
+    # Answer suggestions produced by prefill! for multi-select steps, keyed by
+    # step id. A suggestion pre-populates the step's choices in a renderer but
+    # — unlike an answer — never satisfies skip_if rules: multi-select
+    # extraction is treated as a hint the user confirms and may extend, not a
+    # deterministic fact. Cleared per step once the user answers it.
+    #
+    # @return [Hash{Symbol => Array}]
+    attr_reader :suggestions
+
+    # 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 +47,10 @@ module Inquirex
       @current_step_id = definition.start_step_id
       @validator = validator
       @totals = init_totals
+      @completion_metadata = nil
+      @after_completion_hooks = []
+      @completion_hook_errors = []
+      @suggestions = {}
       @history << @current_step_id
       skip_display_steps_if_needed
     end
@@ -61,6 +91,7 @@ module Inquirex
       raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
       @answers[@current_step_id] = value
+      @suggestions.delete(@current_step_id)
       apply_accumulations(current_step, value)
       advance_step
     end
@@ -95,24 +126,85 @@ module Inquirex
         next if value.respond_to?(:empty?) && value.empty?
 
         sym = key.to_sym
-        @answers[sym] = value unless @answers.key?(sym)
+        if multi_select_step?(sym)
+          # Multi-select extraction is a hint, not a fact: the user may have
+          # more selections in mind than the text revealed. Record it as a
+          # suggestion so renderers pre-check the choices while the question
+          # is still asked; skip_if rules see no answer and do not fire.
+          @suggestions[sym] = Array(value) unless @answers.key?(sym)
+        else
+          @answers[sym] = value unless @answers.key?(sym)
+        end
       end
       skip_if_needed unless finished?
       @answers
     end
 
+    # The prefill suggestion for a step, or nil when none was recorded.
+    #
+    # @param step_id [Symbol, String] step id
+    # @return [Array, nil] suggested selections for a multi-select step
+    def suggestion_for(step_id)
+      @suggestions[step_id.to_sym]
+    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,
+        suggestions:         @suggestions,
+        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 +227,19 @@ 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 = []
+      @suggestions = state[:suggestions] || {}
+    end
+
+    # Whether +step_id+ names a multi-select step in the definition. Unknown
+    # ids (e.g. an extract schema field that matches no step) are not.
+    #
+    # @param step_id [Symbol]
+    # @return [Boolean]
+    def multi_select_step?(step_id)
+      @definition.step_ids.include?(step_id) && @definition.step(step_id).type == :multi_enum
     end
 
     def init_totals
@@ -154,12 +259,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

data/lib/inquirex/rules/less_than.rb

@@ -6,6 +6,8 @@ module Inquirex
     class LessThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol, String] step id whose answer is compared
+      # @param value [Integer] threshold the answer must stay below
       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, is below 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" => "less_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 LessThan rule from a plain Hash.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [LessThan]
       def self.from_h(hash)
         field = hash["field"] || hash[:field]
         value = (hash["value"] || hash[:value]).to_i

data/lib/inquirex/rules/not_empty.rb

@@ -6,12 +6,18 @@ module Inquirex
     class NotEmpty < Base
       attr_reader :field
 
+      # @param field [Symbol, String] step id whose answer is checked for presence
       def initialize(field)
         super()
         @field = field.to_sym
         freeze
       end
 
+      # True when the field's answer is neither nil nor empty
+      # (empty String, Array, Hash, etc. all evaluate false).
+      #
+      # @param answers [Hash{Symbol => Object}] answer context, step_id => value
+      # @return [Boolean]
       def evaluate(answers)
         val = answers[@field]
         return false if val.nil?
@@ -20,14 +26,20 @@ module Inquirex
         true
       end
 
+      # @return [Hash{String => Object}] wire format, same shape .from_h accepts
       def to_h
         { "op" => "not_empty", "field" => @field.to_s }
       end
 
+      # @return [String] human-readable form, e.g. "income_types is not empty"
       def to_s
         "#{@field} is not empty"
       end
 
+      # Deserializes a NotEmpty rule from a plain Hash.
+      #
+      # @param hash [Hash] rule hash with string or symbol keys
+      # @return [NotEmpty]
       def self.from_h(hash)
         field = hash["field"] || hash[:field]
         new(field)

data/lib/inquirex/validation/adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Inquirex
+  # Namespace for pluggable step-answer validation adapters.
   module Validation
     # Result of validating a step answer.
     #

data/lib/inquirex/validation/null_adapter.rb

@@ -5,6 +5,11 @@ module Inquirex
     # No-op validator: always accepts any input.
     # Used by default when no validation adapter is configured.
     class NullAdapter < Adapter
+      # Accepts any input unconditionally.
+      #
+      # @param _node [Node] the current step (ignored)
+      # @param _input [Object] value submitted by the user (ignored)
+      # @return [Result] always valid, with no errors
       def validate(_node, _input)
         Result.new(valid: true)
       end

data/lib/inquirex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inquirex
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end

data/lib/inquirex/widget_registry.rb

@@ -10,6 +10,7 @@ module Inquirex
   # Adapters (TTY, JS, Rails) use this to pick an appropriate renderer when
   # the DSL author has not specified an explicit `widget` hint.
   module WidgetRegistry
+    # Every widget type an adapter may be asked to render, across all contexts.
     WIDGET_TYPES = %i[
       text_input
       textarea

data/lib/inquirex.rb

@@ -24,16 +24,29 @@ require_relative "inquirex/accumulator"
 require_relative "inquirex/node"
 require_relative "inquirex/definition"
 require_relative "inquirex/answers"
+require_relative "inquirex/completion_metadata"
 
 # Validation
 require_relative "inquirex/validation/adapter"
 require_relative "inquirex/validation/null_adapter"
 
+# Post-completion actions
+require_relative "inquirex/actions"
+require_relative "inquirex/actions/template"
+require_relative "inquirex/actions/outbox"
+require_relative "inquirex/actions/base"
+require_relative "inquirex/actions/send_email"
+require_relative "inquirex/actions/webhook"
+require_relative "inquirex/actions/custom"
+require_relative "inquirex/actions/action"
+require_relative "inquirex/actions/runner"
+
 # DSL
 require_relative "inquirex/dsl"
 require_relative "inquirex/dsl/rule_helpers"
 require_relative "inquirex/dsl/step_builder"
 require_relative "inquirex/dsl/flow_builder"
+require_relative "inquirex/dsl/action_builder"
 
 # Engine
 require_relative "inquirex/engine/state_serializer"