inquirex-tty 0.4.0

data/lib/inquirex/tty/output_path.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Shared output path resolution for commands that accept an `-o/--output` option.
+    #
+    # Rules:
+    #   - nil or empty output          → nil (caller should write to stdout)
+    #   - output is an existing dir    → <dir>/<flow-basename>.<ext>
+    #   - output has an extension      → <output> with its extension replaced by .<ext>
+    #   - output has no extension      → <output>.<ext>
+    #
+    # For commands that must always write to a file (e.g. images that cannot go
+    # to stdout), use {.resolve_with_default}, which falls back to
+    # `<flow-basename>.<ext>` in the current directory.
+    module OutputPath
+      module_function
+
+      # Resolves an output path, returning nil when the caller should use stdout.
+      #
+      # @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"
+      # @return [String, nil]
+      def resolve(flow_file, output, extension)
+        return nil if output.nil? || output.to_s.empty?
+        return File.join(output, "#{flow_basename(flow_file)}#{extension}") if File.directory?(output)
+
+        with_default_extension(output, extension)
+      end
+
+      # Resolves an output path, falling back to "<basename>.<ext>" in cwd when
+      # no --output was given. For commands where stdout is not an option.
+      #
+      # @param flow_file [String]
+      # @param output    [String, nil]
+      # @param extension [String]
+      # @return [String]
+      def resolve_with_default(flow_file, output, extension)
+        resolve(flow_file, output, extension) || "#{flow_basename(flow_file)}#{extension}"
+      end
+
+      # The flow file's basename without its extension.
+      #
+      # @param flow_file [String]
+      # @return [String]
+      def flow_basename(flow_file)
+        File.basename(flow_file, File.extname(flow_file))
+      end
+
+      # Ensures `path` ends with the given extension. If the path has no
+      # extension, appends it. If it has one, replaces it.
+      #
+      # @param path      [String]
+      # @param extension [String] including leading dot
+      # @return [String]
+      def with_default_extension(path, extension)
+        if File.extname(path).empty?
+          "#{path}#{extension}"
+        else
+          path.sub(%r{\.[^/.]+\z}, extension)
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tty/renderer.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Renders flow nodes as interactive TTY prompts. Dispatches collecting steps
+    # via the node's TTY widget hint (from +Inquirex::WidgetRegistry+ or an
+    # explicit +widget target: :tty+ declaration in the DSL).
+    #
+    # Display verbs render text/boxes and return +nil+; the caller is responsible
+    # for calling +engine.advance+.
+    #
+    # Widget type → tty-prompt method:
+    #   text_input     → prompt.ask
+    #   multiline      → line-by-line collector (empty line submits)
+    #   number_input   → prompt.ask(convert: :int / :float)
+    #   currency_input → prompt.ask(convert: :float)
+    #   yes_no         → prompt.yes?
+    #   select         → prompt.select
+    #   multi_select   → prompt.multi_select
+    #   enum_select    → prompt.enum_select
+    #   mask           → prompt.mask
+    #   slider         → prompt.slider
+    #   (fallback)     → prompt.ask
+    #
+    # Header display verb uses TTY::Font for large ASCII-art section titles.
+    class Renderer
+      include UIHelper
+
+      # @return [TTY::Prompt]
+      attr_reader :prompt
+
+      # @param prompt [TTY::Prompt] injectable for testing
+      def initialize(prompt: ::TTY::Prompt.new)
+        @prompt = prompt
+      end
+
+      # Prints a "thinking" line before the LLM adapter is called.
+      # Plain colored text — no animation so it plays nicely with piped output.
+      #
+      # @param message [String]
+      # @return [void]
+      def thinking(message)
+        sep(:magenta, "─")
+        puts pastel.bright_magenta.bold(message)
+        sep(:magenta, "─")
+      end
+
+      # Prints the structured data extracted by a clarify step, dimming any
+      # fields the LLM left blank so the user can see what still needs asking.
+      #
+      # @param result [Hash] adapter output
+      # @return [void]
+      def show_extraction(result)
+        puts pastel.bold("📋 LLM extracted:")
+        result.each do |key, value|
+          if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+            puts pastel.dim("  ❓ #{key}: (unknown — will ask)")
+          else
+            puts pastel.green("  ✅ #{key}: #{value.inspect}")
+          end
+        end
+        sep(:magenta, "─")
+      end
+
+      # Renders a node. Returns the collected answer, or +nil+ for display verbs.
+      # @param node [Inquirex::Node]
+      # @return [Object, nil]
+      def render(node)
+        if node.display?
+          render_display_verb(node)
+          nil
+        else
+          render_collecting(node)
+        end
+      end
+
+      private
+
+      # Dispatches display verbs to their styled renderers.
+      # :header uses TTY::Font for a large ASCII-art title.
+      # :btw and :warning use TTY::Box info/warn boxes.
+      # :say outputs plain text.
+      # @param node [Inquirex::Node]
+      # @return [void]
+      def render_display_verb(node)
+        case node.verb
+        when :header
+          render_header(node)
+        when :say
+          puts "\n#{node.text}\n"
+          prompt.keypress(pastel.dim("Press any key to continue..."))
+          sep(:green, "━")
+        when :btw
+          info(node.text)
+          prompt.keypress(pastel.dim("Press any key to continue..."))
+        when :warning
+          warning(node.text)
+          prompt.keypress(pastel.dim("Press any key to continue..."))
+        else
+          puts "\n#{node.text}\n"
+          prompt.keypress(pastel.dim("Press any key to continue..."))
+        end
+      end
+
+      # Renders a header node using TTY::Font for an ASCII-art title.
+      # Falls back to a TTY::Box bordered header if font rendering fails
+      # (e.g. unsupported characters in the text).
+      # @param node [Inquirex::Node]
+      # @return [void]
+      def render_header(node)
+        font = ::TTY::Font.new(:doom)
+        title_text = node.text.upcase
+        title_text.split.each do |_word|
+          title = font.write(node.text.upcase)
+          puts pastel.yellow(title)
+        end
+        sep(:cyan, "━")
+        prompt.keypress(pastel.dim("Press any key to continue..."))
+      rescue StandardError
+        # Fall back to tty-box if TTY::Font cannot render the text
+        puts box(node.text, bg: :blue, fg: :white)
+        prompt.keypress(pastel.dim("Press any key to continue..."))
+        sep(:cyan, "━")
+      end
+
+      # Gets the effective TTY widget hint and dispatches to the right render method.
+      # @param node [Inquirex::Node]
+      # @return [Object]
+      def render_collecting(node)
+        hint = effective_tty_hint(node)
+        method_name = :"render_#{hint.type}"
+        if respond_to?(method_name, true)
+          send(method_name, node)
+        else
+          render_text_input(node)
+        end
+      end
+
+      # Returns the effective TTY widget hint for a node, with a text_input fallback.
+      # @param node [Inquirex::Node]
+      # @return [Inquirex::WidgetHint]
+      def effective_tty_hint(node)
+        hint =
+          if node.respond_to?(:effective_widget_hint_for)
+            node.effective_widget_hint_for(target: :tty)
+          else
+            Inquirex::WidgetRegistry.default_hint_for(node.type, context: :tty)
+          end
+        hint || Inquirex::WidgetHint.new(type: :text_input)
+      end
+
+      # Single-line text.
+      def render_text_input(node)
+        prompt.ask(node.question)
+      end
+
+      # Multi-line text (empty line to submit).
+      def render_multiline(node)
+        puts pastel.bold(node.question)
+        puts pastel.dim("Enter your response. Press Enter on a blank line to submit.")
+        sep(:cyan, "─")
+        collect_multiline_text
+      end
+
+      def collect_multiline_text
+        lines = []
+        loop do
+          line = prompt.ask(">") { |q| q.required(false) }
+          break if line.nil? || line.empty?
+
+          lines << line
+        end
+        sep(:cyan, "─")
+        lines.empty? ? nil : lines.join("\n")
+      end
+
+      # 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:)
+      end
+
+      # Float for currency types.
+      def render_currency_input(node)
+        prompt.ask(node.question, convert: :float)
+      end
+
+      # Boolean — tty-prompt yes?.
+      def render_yes_no(node)
+        prompt.yes?(node.question)
+      end
+
+      # Single-choice scrollable menu.
+      def render_select(node)
+        prompt.select(node.question, select_options(node))
+      end
+
+      # Multiple-choice list (space to toggle, min 1 selection).
+      def render_multi_select(node)
+        prompt.multi_select(node.question, select_options(node), min: 1)
+      end
+
+      # Numbered choice menu.
+      def render_enum_select(node)
+        prompt.enum_select(node.question, select_options(node))
+      end
+
+      # Hidden / masked input.
+      def render_mask(node)
+        prompt.mask(node.question)
+      end
+
+      # Numeric slider. Reads min/max/step from explicit widget hint options.
+      def render_slider(node)
+        opts = {}
+        if node.respond_to?(:effective_widget_hint_for)
+          hint_opts = node.effective_widget_hint_for(target: :tty)&.options || {}
+          opts[:min]  = hint_opts[:min]  if hint_opts[:min]
+          opts[:max]  = hint_opts[:max]  if hint_opts[:max]
+          opts[:step] = hint_opts[:step] if hint_opts[:step]
+        end
+        prompt.slider(node.question, **opts)
+      end
+
+      # Aliases: date, email, phone degrade to plain text_input in TTY.
+      alias render_date_picker  render_text_input
+      alias render_email_input  render_text_input
+      alias render_phone_input  render_text_input
+      # textarea is multiline in TTY
+      alias render_textarea     render_multiline
+
+      # Returns options suitable for TTY::Prompt select/multi_select.
+      # Inquirex exposes option values via `node.options` and display labels
+      # via `node.option_labels` ({value => label}). TTY::Prompt expects a
+      # Hash in the opposite orientation: {label => return_value}.
+      def select_options(node)
+        values = node.options || []
+        labels = node.respond_to?(:option_labels) ? node.option_labels : nil
+        return values unless labels && !labels.empty?
+
+        values.to_h { |v| [labels[v] || v, v] }
+      end
+    end
+  end
+end

data/lib/inquirex/tty/ui_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Mixin providing TTY::Box, Pastel, and screen helpers to CLI commands
+    # and the Renderer. Defines +box+, +sep+, +next_step+, +frame+, +info+,
+    # +success+, +error+, +warning+, and +width+ on the including class.
+    module UIHelper
+      class << self
+        # @return [Pastel] shared Pastel instance
+        def pastel
+          @pastel ||= Pastel.new
+        end
+
+        def included(base)
+          base.extend(Forwardable)
+          base.define_method(:tty_box)    { ::TTY::Box }
+          base.define_method(:tty_screen) { ::TTY::Screen }
+          base.define_method(:pastel)     { ::Inquirex::TTY::UIHelper.pastel }
+
+          %i[frame info success error].each do |method|
+            base.define_method(method) { |*args, **kwargs| puts ::TTY::Box.send(method, *args, **kwargs) }
+          end
+          base.define_method(:warning) { |*args, **kwargs| puts ::TTY::Box.send(:warn, *args, **kwargs) }
+
+          base.def_delegators :tty_screen, :width
+
+          base.class_eval do
+            # Draw a bordered box with optional title.
+            def box(text, title: nil, bg: :green, fg: :white) # rubocop:disable Naming/MethodParameterName
+              w = [width, 80].min
+              args = {
+                width:   w,
+                padding: { top: 0, bottom: 0, left: 1, right: 1 },
+                align:   :center,
+                style:   { fg: fg, bg: bg,
+                         border: { type: :thin, fg: fg, bg: bg } }
+              }
+              args[:title] = { top_left: title } if title
+              frame(text, **args)
+            end
+
+            # Print step progress and separator.
+            def next_step(step_id, step_number)
+              puts pastel.yellow("Step #{step_number}: #{step_id}")
+              sep(:yellow, "━")
+            end
+
+            # Print a full-width separator in the given color.
+            def sep(color = :yellow, char = "━")
+              puts pastel.send(color, char * 80)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tty/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    VERSION = "0.4.0"
+  end
+end

data/lib/inquirex/tty.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "inquirex"
+require "inquirex/llm"
+require "dry/cli"
+require "tty-prompt"
+require "tty-box"
+require "tty-screen"
+require "tty-font"
+require "pastel"
+require "forwardable"
+require "json"
+require "yaml"
+require "time"
+require "shellwords"
+require "tempfile"
+
+module Inquirex
+  # Terminal adapter for Inquirex flows. Renders questions as interactive
+  # TTY prompts via tty-prompt, mapping each data type to the appropriate
+  # widget via Inquirex widget hints.
+  #
+  # Entry point:
+  #   Dry::CLI.new(Inquirex::TTY::Commands).call
+  module TTY
+    # Raised when inquirex-tty encounters a load, validation, or runtime error.
+    class Error < StandardError; end
+  end
+end
+
+require_relative "tty/version"
+require_relative "tty/ui_helper"
+require_relative "tty/flow_loader"
+require_relative "tty/output_path"
+require_relative "tty/renderer"
+require_relative "tty/commands/run"
+require_relative "tty/commands/validate"
+require_relative "tty/commands/graph"
+require_relative "tty/commands/export"
+require_relative "tty/commands/version"
+require_relative "tty/commands"

data/sig/inquirex/tty.rbs

@@ -0,0 +1,6 @@
+module Inquirex
+  module Tty
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,197 @@
+--- !ruby/object:Gem::Specification
+name: inquirex-tty
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: inquirex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: inquirex-llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: tty-box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: tty-font
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: 'Renders Inquirex flow definitions as interactive ANSI terminal wizards
+  using tty-prompt, tty-box, and tty-font. Provides a dry-cli command suite: run,
+  validate, graph, version.'
+email:
+- kigster@gmail.com
+executables:
+- inquirex
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".relaxed_rubocop.yml"
+- ".secrets.baseline"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/badges/coverage_badge.svg
+- examples/01_hello_world.rb
+- examples/02_yes_or_no.rb
+- examples/03_food_preferences.png
+- examples/03_food_preferences.rb
+- examples/04_event_registration.rb
+- examples/05_job_application.rb
+- examples/06_health_assessment.rb
+- examples/07_loan_application.rb
+- examples/08_tax_preparer.rb
+- examples/09_tax_preparer_llm.rb
+- examples/10_answers.json
+- examples/10_real_tax_preparer.rb
+- examples/README.md
+- exe/inquirex
+- justfile
+- lefthook.yml
+- lib/inquirex/tty.rb
+- lib/inquirex/tty/commands.rb
+- lib/inquirex/tty/commands/export.rb
+- lib/inquirex/tty/commands/graph.rb
+- lib/inquirex/tty/commands/run.rb
+- lib/inquirex/tty/commands/validate.rb
+- lib/inquirex/tty/commands/version.rb
+- lib/inquirex/tty/flow_loader.rb
+- lib/inquirex/tty/output_path.rb
+- lib/inquirex/tty/renderer.rb
+- lib/inquirex/tty/ui_helper.rb
+- lib/inquirex/tty/version.rb
+- sig/inquirex/tty.rbs
+homepage: https://github.com/flowengine-rb/inquirex-tty
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/flowengine-rb/inquirex-tty
+  source_code_uri: https://github.com/inquirex/inquirex-tty
+  changelog_uri: https://github.com/inquirex/inquirex-tty/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Terminal adapter for Inquirex flows — interactive TTY wizard via tty-prompt
+test_files: []