inquirex-tty 0.5.0 → 0.9.6

data/examples/makeabox.rb

@@ -0,0 +1,93 @@
+Inquirex.define do
+  start :do_you_have_a_minute
+
+  confirm :do_you_have_a_minute do
+    type :boolean
+    question "Do you you have a few minutes to help us understand how you use the site, what's working and what needs fixing?"
+    widget type: :toggle
+    widget target: :mobile, type: :yes_no_buttons
+    transition to: :name, if_rule: equals(:do_you_have_a_minute, true)
+    transition to: :no_problem
+  end
+
+  ask :name do
+    type :string
+    question "What is your name? However you'd like to be called."
+    widget type: :text_input
+    widget target: :mobile, type: :text_input
+    transition to: :email
+  end
+
+  ask :email do
+    type :email
+    question "Please share with us your email address so that we can notify you when your ideas and feedback has been put to good use."
+    widget type: :email_input
+    widget target: :mobile, type: :email_input
+    transition to: :other_tools
+  end
+
+  say :no_problem do
+    text "Not a problem. If you ever change your mind, just hit that round circle and answer the quesitons,. Adios!"
+  end
+
+  ask :other_tools do
+    type :boolean
+    question "Do you use any other online tools for generating laser cuts or engraving?"
+    default false
+    transition to: :uses_other_tools, if_rule: equals(:other_tools, true)
+    transition to: :how_long_you_used_makeabox
+  end
+
+  ask :uses_other_tools do
+    type :multi_enum
+    question "May we ask which tools do you use to building enclosures cut with a laser cutter? If the tool you use is not listed, choose Unlisted."
+    options i_dont: "I don't use Any of Them",
+      makeabox: "MakeABox.io (this site)",
+      makercase: "Makercase",
+      boxes_py: "Boxes.py",
+      www_atomm_com: "Atomm.com",
+      vector_painter: "Vector Painter.com",
+      laserbiz_ru: "Laserbiz.ru",
+      hessmer_org_gears: "hessmer.org/gears",
+      unlisted: "Unlisted (Other)"
+    transition to: :makeabox_only, if_rule: contains(:uses_other_tools, "makeabox")
+    transition to: :other, if_rule: contains(:uses_other_tools, "unlisted")
+    transition to: :feedback
+  end
+
+  say :makeabox_only do
+    text "Thanks for using MakeABox only :) We hope to improve this application futher and we appreciate your choice, considering there are a few out there :)"
+    transition to: :how_long_you_used_makeabox
+  end
+
+  ask :how_long_you_used_makeabox do
+    type :enum
+    question "Give us a sense about how long have you been used MakeABox.io..."
+    options first_time: "My First TIme",
+      about_a_month: "About a Month",
+      a_few_months: "A few Months",
+      at_least_a_year: "At least a Year",
+      over_a_year: "Over a Year",
+      over_two_years: "Over two Years"
+    default :first_time
+    transition to: :other, if_rule: contains(:uses_other_tools, "unlisted")
+    transition to: :feedback
+  end
+
+  ask :other do
+    type :text
+    widget type: :text_input
+    question "Can you list the tools not listed in the previous question?"
+    transition to: :feedback
+  end
+
+  ask :feedback do
+    question "Pelase provide any feedback or bug reports that will make MakeABox.io better."
+    type :text
+    transition to: :thanks
+  end
+
+  say :thanks do
+    text "We appreciate you taking the time to answer some of the questions! See you around!"
+  end
+end

data/exe/inqt

@@ -0,0 +1 @@
+inquirex-tty

data/justfile

@@ -4,7 +4,26 @@ set shell := ["bash", "-c"]
 
 repo := 'git@github.com:inquirex/inquirex-tty.git'
 version := `grep VERSION lib/inquirex/tty/version.rb | awk '{print $3}' | tr -d '"' | tr -d '\n'`
-rbenv := 'eval "$(rbenv init bash)"; bundle exec '
+# The `-` matters: `rbenv init bash` prints human instructions ("skipping
+# ~/.bash_login: already configured"), which eval then tries to run and the
+# recipe dies with "skipping: command not found". `rbenv init - bash` prints
+# the shell code that is meant to be eval'd.
+rbenv := 'eval "$(rbenv init - bash 2>/dev/null || true)"; bundle exec '
+
+# 1Password secret reference for the RubyGems TOTP, and the full path to `op`
+# because a recipe does not inherit an interactive shell's PATH.
+# The account is NOT named here: it is a private 1Password address and this
+# file is public. `op` reads it from OP_ACCOUNT, exported by the ecosystem
+# root's .envrc, which lives outside every repo. Two accounts are
+# registered and only one holds the open-source-repos vault, so without
+# OP_ACCOUNT the read can resolve against the wrong one, return nothing,
+# and publish silently falls back to prompting mid-release.
+op := '/opt/homebrew/bin/op'
+otp_ref := 'op://open-source-repos/ruby-gems/one-time password?attribute=otp'
+
+gem_name := 'inquirex-tty'
+gem_file := 'pkg/' + gem_name + '-' + version + '.gem'
+gem_url  := 'https://rubygems.org/gems/' + gem_name
 
 [no-exit-message]
 recipes:
@@ -29,15 +48,15 @@ format:
 
 # Run a flow interactively
 run flow_file:
-    {{ rbenv }} exe/inquirex-tty run {{flow_file}}
+    {{ rbenv }} exe/inqt run {{flow_file}}
 
 # Validate a flow definition
 validate flow_file:
-    {{ rbenv }} exe/inquirex-tty validate {{flow_file}}
+    {{ rbenv }} exe/inqt validate {{flow_file}}
 
 # Export a flow as a Mermaid diagram (stdout)
 graph flow_file:
-    {{ rbenv }} exe/inquirex-tty graph {{flow_file}}
+    {{ rbenv }} exe/inqt graph {{flow_file}}
 
 # Validate all examples
 examples:
@@ -45,7 +64,7 @@ examples:
     set -e
     for f in examples/*.rb; do
         echo "=== $f ==="
-        {{ rbenv }} exe/inquirex validate "$f"
+        {{ rbenv }} exe/inqt validate "$f"
         echo ""
     done
 
@@ -59,12 +78,45 @@ clean:
     /usr/bin/find . -name .DS_Store -delete -print || true
     rm -rf tmp/*
 
-# Create
-publish: build
-    {{ rbenv }} rake release[remote]
-
-version:
-    @echo "{{ version }}"
+# `gem push` rather than `rake release`: release also guards the tree, tags and
+# pushes git — which `just release` does deliberately and separately — and it
+# gives no way to pass a 2FA code, so it always stopped to prompt.
+#
+# The code comes from 1Password unless one is passed in:
+#
+#   just publish            # read the code from 1Password
+#   just publish 123456     # use this code
+#
+# `just publish-all` in inquirex-tools passes one, because a TOTP is single-use:
+# four gems reading the same 30-second window would have the second push
+# rejected as a replay.
+#
+# Build the .gem and push it to RubyGems, non-interactively
+publish otp="": build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    eval "$(rbenv init - bash 2>/dev/null || true)"
+
+    mkdir -p pkg
+    gem build {{ gem_name }}.gemspec --output "{{ gem_file }}"
+
+    # `|| true` is load-bearing: under `set -e` a failed `op read` — not signed
+    # in to 1Password, item renamed, op not installed — would abort the recipe
+    # before the prompting fallback below could run.
+    otp="{{ otp }}"
+    [[ -n "${otp}" ]] || otp=$({{ op }} read "{{ otp_ref }}" 2>/dev/null || true)
+
+    if [[ -n "${otp}" ]]; then
+      gem push "{{ gem_file }}" --otp "${otp}"
+    else
+      echo "rubygems: no OTP available — gem push will prompt if 2FA is required."
+      gem push "{{ gem_file }}"
+    fi
+
+    # Only reachable when the push succeeded: `set -e` aborts the recipe on a
+    # non-zero `gem push`, so the page never opens for a release that failed.
+    echo "published {{ gem_name }} {{ version }} → {{ gem_url }}"
+    open "{{ gem_url }}" 2>/dev/null || xdg-open "{{ gem_url }}" 2>/dev/null || true
 
 # Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
 release:

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?
@@ -55,7 +57,8 @@ module Inquirex
               renderer.render(step)
               engine.advance
             else
-              engine.answer(renderer.render(step))
+              suggestion = engine.suggestion_for(engine.current_step_id)
+              engine.answer(renderer.render(step, suggestion:))
             end
           end
 
@@ -183,11 +186,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,15 +63,28 @@ module Inquirex
       end
 
       # Renders a node. Returns the collected answer, or +nil+ for display verbs.
+      #
+      # @example Collect an answer for the current step, pre-checking LLM suggestions
+      #   renderer = Inquirex::TTY::Renderer.new
+      #   step   = engine.current_step
+      #   answer = renderer.render(step, suggestion: engine.suggestion_for(engine.current_step_id))
+      #   engine.answer(answer) unless step.display?
+      #
       # @param node [Inquirex::Node]
+      # @param suggestion [Array, nil] prefill suggestion for the step (option
+      #   form values, e.g. from Engine#suggestion_for) — multi-select prompts
+      #   render these choices pre-checked so the user confirms or extends
       # @return [Object, nil]
-      def render(node)
+      def render(node, suggestion: nil)
+        @current_suggestion = suggestion
         if node.display?
           render_display_verb(node)
           nil
         else
           render_collecting(node)
         end
+      ensure
+        @current_suggestion = nil
       end
 
       private
@@ -177,12 +190,51 @@ module Inquirex
       # Integer or float depending on the node's data type.
       def render_number_input(node)
         convert = node.type == :integer ? :int : :float
-        prompt.ask(node.question, convert:)
+        ask_bounded(node, convert:)
       end
 
       # Float for currency types.
       def render_currency_input(node)
-        prompt.ask(node.question, convert: :float)
+        ask_bounded(node, convert: :float)
+      end
+
+      # Asks for a number, enforcing the node's declared bounds.
+      #
+      # tty-prompt's `in:` re-asks until the answer falls inside the range,
+      # which is the terminal's equivalent of the widget's stepper bounds — the
+      # user is corrected before the value is ever stored, rather than having it
+      # silently clamped afterwards. An unbounded node keeps the plain ask so
+      # the prompt text is unchanged for the overwhelmingly common case.
+      #
+      # @param node [Inquirex::Node] the step being rendered
+      # @param convert [Symbol] :int or :float
+      # @return [Numeric, nil]
+      def ask_bounded(node, convert:)
+        return prompt.ask(node.question, convert:) unless node.bounded?
+
+        prompt.ask(node.question, convert:, in: bounds_range(node)) do |q|
+          q.messages[:range?] = "Enter a value #{describe_bounds(node)}."
+        end
+      end
+
+      # The node's bounds as a Range tty-prompt understands. An open end is
+      # spelled with infinity rather than omitted, since `in:` wants a Range.
+      #
+      # @param node [Inquirex::Node]
+      # @return [Range]
+      def bounds_range(node)
+        low  = node.min || -Float::INFINITY
+        high = node.max || Float::INFINITY
+        low..high
+      end
+
+      # @param node [Inquirex::Node]
+      # @return [String] human phrasing of whichever bounds exist
+      def describe_bounds(node)
+        return "between #{node.min} and #{node.max}" if node.min && node.max
+        return "of #{node.min} or more" if node.min
+
+        "of #{node.max} or less"
       end
 
       # Boolean — tty-prompt yes?.
@@ -195,9 +247,26 @@ module Inquirex
         prompt.select(node.question, select_options(node))
       end
 
-      # Multiple-choice list (space to toggle, min 1 selection).
+      # Multiple-choice list (space to toggle, min 1 selection). Suggested
+      # choices (an LLM extraction the user should confirm) render pre-checked.
       def render_multi_select(node)
-        prompt.multi_select(node.question, select_options(node), min: 1)
+        prompt.multi_select(node.question, select_options(node), min: 1, **multi_select_defaults(node))
+      end
+
+      # tty-prompt pre-checks multi_select choices via default: choice NAMES —
+      # the labels, not the return values. Suggestions arrive as option form
+      # values (that is the wire contract), so translate value → label here;
+      # a value with no label entry falls back to itself.
+      #
+      # @param node [Inquirex::Node]
+      # @return [Hash] {} or { default: Array<String> }
+      def multi_select_defaults(node)
+        suggested = Array(@current_suggestion)
+        return {} if suggested.empty?
+
+        labels = node.respond_to?(:option_labels) ? node.option_labels : nil
+        names = suggested.map { |value| labels&.fetch(value.to_s, nil) || value.to_s }
+        { default: names }
       end
 
       # Numbered choice menu.

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.9.6"
   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