inquirex 0.4.1 → 0.6.0

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

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.4.1"
+  VERSION = "0.6.0"
 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"

metadata

@@ -1,21 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 description: Inquirex lets you define multi-step questionnaires as directed graphs
   with conditional branching, using a conversational DSL (ask, say, mention) and an
   AST-based rule system (contains, equals, greater_than, all, any). The engine walks
   the graph, collects structured answers, and serializes everything to JSON — making
   it the ideal backbone for cross-platform intake forms where the frontend is a chat
-  widget, a terminal, or a mobile app. Framework-agnostic, zero dependencies, thread-safe
-  immutable definitions.
+  widget, a terminal, or a mobile app. Framework-agnostic, no third-party dependencies,
+  thread-safe immutable definitions.
 email:
 - kigster@gmail.com
 executables: []
@@ -32,13 +46,29 @@ files:
 - README.md
 - Rakefile
 - docs/badges/coverage_badge.svg
+- examples/01_readme_example.rb
+- examples/02_readme_mermaid.png
+- examples/02_readme_mermaid.rb
+- examples/03_send_email_actions.rb
+- examples/README.md
 - justfile
 - lefthook.yml
 - lib/inquirex.rb
 - lib/inquirex/accumulator.rb
+- lib/inquirex/actions.rb
+- lib/inquirex/actions/action.rb
+- lib/inquirex/actions/base.rb
+- lib/inquirex/actions/custom.rb
+- lib/inquirex/actions/outbox.rb
+- lib/inquirex/actions/runner.rb
+- lib/inquirex/actions/send_email.rb
+- lib/inquirex/actions/template.rb
+- lib/inquirex/actions/webhook.rb
 - lib/inquirex/answers.rb
+- lib/inquirex/completion_metadata.rb
 - lib/inquirex/definition.rb
 - lib/inquirex/dsl.rb
+- lib/inquirex/dsl/action_builder.rb
 - lib/inquirex/dsl/flow_builder.rb
 - lib/inquirex/dsl/rule_helpers.rb
 - lib/inquirex/dsl/step_builder.rb
@@ -68,7 +98,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/inquirex/inquirex
+  homepage_uri: https://qualified.at
   source_code_uri: https://github.com/inquirex/inquirex
   changelog_uri: https://github.com/inquirex/inquirex/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'