inquirex-tty 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d2a11293b1ac438c2ccd3b25cf1b18782e9b49e9b3e1d4d344e84216403cca9
-  data.tar.gz: d4001771880c748982dbaa765a390f910d4d0e71772259981bb317af0c2696c7
+  metadata.gz: a2984ed233d95ddd841ed94f02795d8489c2d93897a317c846985cc8b88b807b
+  data.tar.gz: e082b1ac879a6a8384ad1f9aa89de557ccb9f483933fad7d474116e1670b3a36
 SHA512:
-  metadata.gz: '085bb14fd6cd73b341108763e61989b882ad4936f7b70ffd2a45089bd5bc930887ab7e7d85b8e2c15e682c77bdb8ba7384971a102199ae74038f2696c0af71dd'
-  data.tar.gz: c6c92ee9cd25e7b23b1a0d6a839f7df0f92bc6a6a36c385a33ee2be4bd01004261c476bb4cf2a5689a2eca10afca1cfd23334546c4c12da7c4e89e42602ebc8f
+  metadata.gz: e84d7ae1c21cd3113399327024b9020b81e4c69323605b98d29fc6c20002884902a8396047f2628598e16e4d4bbc87aa35943b3e4a51e9816200390b218882b7
+  data.tar.gz: 060a278fd838977a0ab5885e7d5e11000e25e004f0d6173729c7194a059d57c061afcc34a0d05929270bdecee01bc72cdf8dd042de9ce4204a7cc2053000001b

data/docs/badges/coverage_badge.svg

@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
     <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
     <text x="31.5" y="14">coverage</text>
-    <text x="80" y="15" fill="#010101" fill-opacity=".3">99%</text>
-    <text x="80" y="14">99%</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">98%</text>
+    <text x="80" y="14">98%</text>
   </g>
 </svg>

data/examples/10_real_tax_preparer.rb

@@ -49,6 +49,38 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
          "Please do NOT enter any personal information: no names,\n" \
          "SSN, ITIN, addresses, or account numbers. We only need\n" \
          "enough to quote a fee."
+    transition to: :describe
+  end
+
+  # -----------------------------------------------------------------------
+  # Opening
+  # -----------------------------------------------------------------------
+
+  ask :describe do
+    type :text
+    question "Describe your last year's tax situation, your residency/citizenship status, your filing status, any dependents, various income types, which state(s) you are filing in,and whether you have your prior year returns available. If you also participate in businesses, please describe their tax status (S-Corp, LLC, etc), and if you have any foreign investments or property."
+    transition to: :summary
+  end
+
+  extract :summary do
+    from :describe
+    prompt "Extract the filer's tax intake details for scoping: filing_status, " \
+           "number of dependents, income_types, state_filing (which states they " \
+           "file in), residency_status, prior_return_available, and any " \
+           "business_entities they own or partner in."
+    schema filing_status:     { type: :enum, values: %w[single married_filing_jointly married_filing_separately
+                                                        head_of_household widowed] },
+      dependents:             { type: :enum, values: %w[0 1 2 3 4+] },
+      income_types:           { type: :multi_enum, values: %w[W2 1099_nec 1099_k business investment crypto rental
+                                                              retirement social_sec gambling foreign home_sale
+                                                              inheritance none] },
+      state_filing:           { type: :multi_enum, values: US_STATES },
+      residency_status:       { type: :enum, values: %w[us_person resident non_resident dual_status] },
+      prior_return_available: { type: :enum, values: %w[yes_last_year yes_older no first_time] },
+      business_entities:      { type: :multi_enum, values: %w[sole_prop single_llc multi_llc s_corp c_corp
+                                                              partnership trust nonprofit] }
+
+    model :claude_sonnet
     transition to: :residency_status
   end
 
@@ -59,6 +91,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :residency_status do
     type :enum
     question "Which best describes your US tax residency for 2025?"
+    skip_if not_empty(:residency_status)
     options({
       "us_person"    => "US citizen or permanent resident",
       "resident"     => "Resident alien (substantial presence)",
@@ -74,6 +107,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :prior_return_available do
     type :enum
     question "Do you have a copy of your most recent tax return?"
+    skip_if not_empty(:prior_return_available)
     options({
       "yes_last_year" => "Yes, last year's return",
       "yes_older"     => "Yes, but older than last year",
@@ -88,6 +122,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :filing_status do
     type :enum
     question "What is your filing status for 2025?"
+    skip_if not_empty(:filing_status)
     options({
       "single"                    => "Single",
       "married_filing_jointly"    => "Married Filing Jointly",
@@ -98,12 +133,13 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
     widget target: :tty,     type: :select
     widget target: :desktop, type: :radio_group, columns: 1
     widget target: :mobile,  type: :dropdown
-    transition to: :dependents_band
+    transition to: :dependents
   end
 
-  ask :dependents_band do
+  ask :dependents do
     type :enum
     question "How many dependents will you claim?"
+    skip_if not_empty(:dependents)
     options %w[0 1 2 3 4+]
     widget target: :tty,     type: :select
     widget target: :desktop, type: :radio_group, columns: 5
@@ -118,6 +154,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :income_types do
     type :multi_enum
     question "Select every type of income you had in 2025."
+    skip_if not_empty(:income_types)
     options({
       "W2"          => "W-2 wages",
       "1099_nec"    => "1099-NEC (contractor)",
@@ -166,6 +203,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :business_entities do
     type :multi_enum
     question "Which business entity types do you own or partner in?"
+    skip_if not_empty(:business_entities)
     options({
       "sole_prop"   => "Sole Proprietor / Schedule C",
       "single_llc"  => "Single-member LLC",
@@ -435,6 +473,7 @@ Inquirex.define id: "tax-preparer-2025", version: "2.0.0" do
   ask :state_filing do
     type :multi_enum
     question "Select every state (and DC) you need to file a return in."
+    skip_if not_empty(:state_filing)
     options US_STATES
     widget target: :tty,     type: :multi_select
     widget target: :desktop, type: :checkbox_group, columns: 10, layout: :grid

data/lib/inquirex/tty/commands/export.rb

@@ -12,9 +12,11 @@ module Inquirex
       #   inquirex export examples/08_tax_preparer.rb -f yml -o . # write 08_tax_preparer.yml to cwd
       #   inquirex export examples/08_tax_preparer.rb -o out.json # write to out.json
       class Export < Dry::CLI::Command
+        # Multi-line help text shown by `inquirex export --help`.
         LONG_DESCRIPTION = "Export a flow definition as JSON or YAML.\n\n" \
                            "Example:\n  inquirex export examples/08_tax_preparer.rb -f yml -o ."
 
+        # One-line summary shown in the top-level command listing.
         SHORT_DESCRIPTION = "Export a flow definition as JSON or YAML ."
 
         if ARGV[0] == "export"
@@ -44,7 +46,7 @@ module Inquirex
           content = serialize(definition, format)
           write(content, flow_file, options[:output], extension_for(format))
         rescue Inquirex::TTY::Error => e
-          warn "Error: #{e.message}"
+          $stderr.puts "Error: #{e.message}"
           exit 1
         end
 
@@ -73,7 +75,7 @@ module Inquirex
           end
 
           File.write(path, content)
-          warn "Exported to #{path}"
+          $stderr.puts "Exported to #{path}"
         end
       end
     end

data/lib/inquirex/tty/commands/graph.rb

@@ -5,11 +5,13 @@ module Inquirex
     module Commands
       # Exports a flow definition as a Mermaid flowchart (stdout or file).
       class Graph < Dry::CLI::Command
+        # Multi-line help text shown by `inquirex graph --help`.
         LONG_DESCRIPTION = "Export a flow definition as a Mermaid diagram source, an image, or both.\n  " \
                            "Image generation requires mermaid-cli (npm install -g @mermaid-js/mermaid-cli)\n  " \
                            "which this gem will attempt to install for you if mmdc command is not available.\n\n" \
                            "Example:\n  inquirex graph qualify_dsl.rb --format both --output ~/Desktop --open"
 
+        # One-line summary shown in the top-level command listing.
         SHORT_DESCRIPTION = "Export a flow definition as a Mermaid diagram source, an image, or both."
 
         if ARGV[0] == "graph"
@@ -54,7 +56,7 @@ module Inquirex
             write_image(source, OutputPath.resolve_with_default(flow_file, output, ".png"), options[:open])
           end
         rescue Inquirex::TTY::Error => e
-          warn "Error: #{e.message}"
+          $stderr.puts "Error: #{e.message}"
           exit 1
         end
 
@@ -66,7 +68,7 @@ module Inquirex
             return
           end
           File.write(output_path, source)
-          warn "Diagram written to #{output_path}"
+          $stderr.puts "Diagram written to #{output_path}"
         end
 
         def write_image(source, output_path, open_file)
@@ -81,14 +83,14 @@ module Inquirex
             )
           end
 
-          warn "Diagram written to #{output_path}"
+          $stderr.puts "Diagram written to #{output_path}"
           open_image_file(output_path) if open_file
         end
 
         def ensure_mermaid_cli_installed!
           return if command_available?("mmdc")
 
-          warn "Installing @mermaid-js/mermaid-cli..."
+          $stderr.puts "Installing @mermaid-js/mermaid-cli..."
           installed = system("npm install -g @mermaid-js/mermaid-cli")
           return if installed && command_available?("mmdc")
 

data/lib/inquirex/tty/commands/run.rb

@@ -22,7 +22,7 @@ module Inquirex
             File.write(options[:output], json)
             puts "\nResults saved to #{options[:output]}"
           else
-            $stderr.puts json # rubocop:disable Style/StderrPuts
+            $stderr.puts json
           end
         rescue Inquirex::TTY::Error => e
           error(e.message)
@@ -43,6 +43,8 @@ module Inquirex
           renderer   = Renderer.new
           adapter    = build_llm_adapter
 
+          engine.after_completion { |eng| eng.completion_metadata = build_completion_metadata }
+
           show_banner(definition)
 
           until engine.finished?
@@ -183,11 +185,56 @@ module Inquirex
           {
             flow_file:       flow_file,
             path_taken:      engine.history,
-            answers:         engine.answers,
+            answers:         engine.answers_with_metadata,
             steps_completed: engine.history.length,
             completed_at:    Time.now.iso8601
           }
         end
+
+        # Rich completion metadata for the answers. Only :engine and
+        # :engine_version are guaranteed — the environment probes are
+        # best-effort: a failing one (offline host, no login name, blocked
+        # egress) yields nil and its member is dropped.
+        #
+        # @return [Inquirex::CompletionMetadata]
+        def build_completion_metadata
+          optional = {
+            uname:     best_effort { OpenStruct.new(Etc.uname) },
+            user:      best_effort { Etc.getlogin },
+            local_ip:  best_effort { local_ip },
+            public_ip: best_effort { public_ip },
+            terminal:  ENV["LC_TERMINAL"] || ENV["TERM_PROGRAM"] || "Unknown"
+          }.compact
+          Inquirex::CompletionMetadata.new(
+            engine:         "inquirex-tty",
+            engine_version: Inquirex::TTY::VERSION,
+            **optional
+          )
+        end
+
+        def best_effort
+          yield
+        rescue StandardError
+          nil
+        end
+
+        # The local address the OS would route out through — a UDP "connect"
+        # picks the outbound interface without sending a single packet.
+        def local_ip
+          UDPSocket.open do |socket|
+            socket.connect("8.8.8.8", 1)
+            socket.addr.last
+          end
+        end
+
+        # Short timeouts so a slow or airgapped network can never stall the
+        # CLI at completion time.
+        def public_ip
+          Net::HTTP.start("api.ipify.org", 443, use_ssl: true, open_timeout: 2, read_timeout: 2) do |http|
+            response = http.get("/")
+            response.is_a?(Net::HTTPSuccess) ? response.body.to_s.strip : nil
+          end
+        end
       end
     end
   end

data/lib/inquirex/tty/commands/validate.rb

@@ -23,10 +23,10 @@ module Inquirex
             exit 1
           end
         rescue Inquirex::TTY::Error => e
-          warn "Error: #{e.message}"
+          $stderr.puts "Error: #{e.message}"
           exit 1
         rescue Inquirex::Errors::Error => e
-          warn "Definition error: #{e.message}"
+          $stderr.puts "Definition error: #{e.message}"
           exit 1
         end
 
@@ -48,8 +48,8 @@ module Inquirex
         end
 
         def print_errors(errors)
-          warn "Flow definition has #{errors.length} error(s):"
-          errors.each { |e| warn "  - #{e}" }
+          $stderr.puts "Flow definition has #{errors.length} error(s):"
+          errors.each { |e| $stderr.puts "  - #{e}" }
         end
 
         def validate_definition(definition)

data/lib/inquirex/tty/commands/version.rb

@@ -7,7 +7,9 @@ module Inquirex
       class Version < Dry::CLI::Command
         desc "Print version information"
 
-        # @param **_ [Hash] ignored options
+        # Prints the version of this gem and of the core inquirex gem.
+        # Any CLI options are accepted and ignored.
+        #
         # @return [void]
         def call(**)
           puts "inquirex-tty #{Inquirex::TTY::VERSION}"

data/lib/inquirex/tty/flow_loader.rb

@@ -6,6 +6,12 @@ module Inquirex
     # binding. The file is expected to call +Inquirex.define+ and return an
     # +Inquirex::Definition+.
     class FlowLoader
+      # Loads and evaluates a flow definition file in one call.
+      #
+      # @example Load a flow definition from disk
+      #   definition = Inquirex::TTY::FlowLoader.load("examples/08_tax_preparer.rb")
+      #   definition.step_ids # => [:filing_status, :dependents, ...]
+      #
       # @param path [String] path to a .rb flow definition file
       # @return [Inquirex::Definition]
       # @raise [Inquirex::TTY::Error] if file is missing, not .rb, or has syntax errors

data/lib/inquirex/tty/output_path.rb

@@ -18,6 +18,11 @@ module Inquirex
 
       # Resolves an output path, returning nil when the caller should use stdout.
       #
+      # @example Resolve the --output option for a JSON export
+      #   OutputPath.resolve("flows/intake.rb", nil, ".json")    # => nil (stdout)
+      #   OutputPath.resolve("flows/intake.rb", "out", ".json")  # => "out.json"
+      #   OutputPath.resolve("flows/intake.rb", "/tmp", ".json") # => "/tmp/intake.json"
+      #
       # @param flow_file [String] source .rb flow file (basename used for defaults)
       # @param output    [String, nil] value of the --output option
       # @param extension [String] including leading dot, e.g. ".json"

data/lib/inquirex/tty/renderer.rb

@@ -63,6 +63,13 @@ module Inquirex
       end
 
       # Renders a node. Returns the collected answer, or +nil+ for display verbs.
+      #
+      # @example Collect an answer for the current step
+      #   renderer = Inquirex::TTY::Renderer.new
+      #   step   = engine.current_step
+      #   answer = renderer.render(step) # nil for display verbs
+      #   engine.answer(answer) unless step.display?
+      #
       # @param node [Inquirex::Node]
       # @return [Object, nil]
       def render(node)

data/lib/inquirex/tty/ui_helper.rb

@@ -12,6 +12,13 @@ module Inquirex
           @pastel ||= Pastel.new
         end
 
+        # Module hook that installs the UI helpers on the including class:
+        # +tty_box+, +tty_screen+, +pastel+, the TTY::Box wrappers (+frame+,
+        # +info+, +success+, +error+, +warning+), the +width+ delegator, and
+        # the +box+ / +next_step+ / +sep+ convenience methods.
+        #
+        # @param base [Class, Module] the class or module including UIHelper
+        # @return [void]
         def included(base)
           base.extend(Forwardable)
           base.define_method(:tty_box)    { ::TTY::Box }
@@ -27,6 +34,12 @@ module Inquirex
 
           base.class_eval do
             # Draw a bordered box with optional title.
+            #
+            # @param text [String] text to display inside the box
+            # @param title [String, nil] optional title on the top border
+            # @param bg [Symbol] background color name
+            # @param fg [Symbol] foreground color name
+            # @return [void]
             def box(text, title: nil, bg: :green, fg: :white) # rubocop:disable Naming/MethodParameterName
               w = [width, 80].min
               args = {
@@ -41,12 +54,21 @@ module Inquirex
             end
 
             # Print step progress and separator.
+            #
+            # @param step_id [Symbol, String] id of the step about to run
+            # @param step_number [Integer] 1-based position in the flow
+            # @return [void]
             def next_step(step_id, step_number)
+              puts
               puts pastel.yellow("Step #{step_number}: #{step_id}")
               sep(:yellow, "━")
             end
 
             # Print a full-width separator in the given color.
+            #
+            # @param color [Symbol] Pastel color name
+            # @param char [String] character repeated across the line
+            # @return [void]
             def sep(color = :yellow, char = "━")
               puts pastel.send(color, char * 80)
             end

data/lib/inquirex/tty/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module TTY
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/inquirex/tty.rb

@@ -14,7 +14,15 @@ require "yaml"
 require "time"
 require "shellwords"
 require "tempfile"
+require "etc"
+require "socket"
+require "net/http"
+require "uri"
+require "ostruct"
 
+# Top-level namespace shared by every gem in the Inquirex family.
+# The core gem defines the DSL, rules, and engine; this gem adds the
+# terminal adapter under {Inquirex::TTY}.
 module Inquirex
   # Terminal adapter for Inquirex flows. Renders questions as interactive
   # TTY prompts via tty-prompt, mapping each data type to the appropriate

data/sig/inquirex/tty.rbs

@@ -1,4 +1,5 @@
 module Inquirex
+  # RBS scaffold namespace for the inquirex-tty gem's type signatures.
   module Tty
     VERSION: String
     # See the writing guide of rbs: https://github.com/ruby/rbs#guides

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-tty
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -29,28 +29,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: inquirex-llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
+- !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'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement