inquirex-tty 0.4.0

data/justfile

@@ -0,0 +1,56 @@
+# © 2026 Konstantin Gredeskoul
+
+set shell := ["bash", "-eu", "-o", "pipefail", "-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'`
+
+# Run full test suite with coverage
+test:
+    bundle exec rspec --format documentation
+
+# Run RuboCop linter
+lint:
+    bundle exec rubocop
+
+# Auto-correct RuboCop offenses
+format:
+    bundle exec rubocop -A
+
+# Run a flow interactively
+run flow_file:
+    bundle exec exe/inquirex-tty run {{flow_file}}
+
+# Validate a flow definition
+validate flow_file:
+    bundle exec exe/inquirex-tty validate {{flow_file}}
+
+# Export a flow as a Mermaid diagram (stdout)
+graph flow_file:
+    bundle exec exe/inquirex-tty graph {{flow_file}}
+
+# Validate all examples
+examples:
+    #!/usr/bin/env bash
+    set -e
+    for f in examples/*.rb; do
+        echo "=== $f ==="
+        bundle exec exe/inquirex-tty validate "$f"
+        echo ""
+    done
+
+# Run all tests then lint
+ci: test lint
+
+alias check-all := ci
+
+version:
+    @echo "{{ version }}"
+
+# Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
+release:
+    git fetch --tags
+    git tag -f "v{{ version }}"
+    git push -f --tags
+    gh release delete -y "v{{ version }}" --repo {{ repo }} 2>/dev/null || true
+    gh release create "v{{ version }}" --generate-notes --repo {{ repo }}

data/lefthook.yml

@@ -0,0 +1,36 @@
+output:
+  - summary
+  - failure
+
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint
+      run: bundle exec rubocop -c .rubocop.yml {staged_files}
+      glob: "*.{rb,Gemfile}"
+      stage_fixed: true
+
+    - name: check for conflict markers and whitespace issues
+      run: git --no-pager diff --check
+
+    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
+    - name: run tests
+      run: just test
+
+    - name: fix rubocop formatting issues
+      run: bundle exec rubocop -a {staged_files}
+      glob: "*.{rb,Gemfile,gemspec}"
+      stage_fixed: true
+
+    - name: spell check
+      run: codespell {staged_files}
+      glob: "*.{rb,md,gemspec}"
+      exclude: "examples/*"
+
+    - name: format markdown
+      run: mdformat {staged_files}
+      glob: "*.md"
+      stage_fixed: true
+
+    - name: scan for secrets
+      run: detect-secrets-hook --baseline .secrets.baseline

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    module Commands
+      # Exports a flow definition as JSON or YAML (stdout or file).
+      #
+      # Examples:
+      #   inquirex export examples/08_tax_preparer.rb             # JSON to stdout
+      #   inquirex export examples/08_tax_preparer.rb -f yml      # YAML to stdout
+      #   inquirex export examples/08_tax_preparer.rb -o .        # write 08_tax_preparer.json to cwd
+      #   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
+        LONG_DESCRIPTION = "Export a flow definition as JSON or YAML.\n\n" \
+                           "Example:\n  inquirex export examples/08_tax_preparer.rb -f yml -o ."
+
+        SHORT_DESCRIPTION = "Export a flow definition as JSON or YAML ."
+
+        if ARGV[0] == "export"
+          desc LONG_DESCRIPTION
+        else
+          desc SHORT_DESCRIPTION
+        end
+
+        argument :flow_file,
+          required: true,
+          desc:     "Path to flow definition (.rb file)"
+        option :format,
+          aliases: ["-f"],
+          default: "json",
+          values:  %w[json yaml yml],
+          desc:    "Output format"
+        option :output,
+          aliases: ["-o"],
+          desc:    "Output file or directory (default: stdout)"
+
+        # @param flow_file [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(flow_file:, **options)
+          definition = FlowLoader.load(flow_file)
+          format = normalize_format(options[:format])
+          content = serialize(definition, format)
+          write(content, flow_file, options[:output], extension_for(format))
+        rescue Inquirex::TTY::Error => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def normalize_format(format)
+          %w[yaml yml].include?(format.to_s) ? "yaml" : "json"
+        end
+
+        def serialize(definition, format)
+          case format
+          when "yaml" then definition.to_h.to_yaml
+          else             JSON.pretty_generate(definition.to_h)
+          end
+        end
+
+        def extension_for(format)
+          format == "yaml" ? ".yml" : ".json"
+        end
+
+        def write(content, flow_file, output, extension)
+          path = OutputPath.resolve(flow_file, output, extension)
+          unless path
+            $stdout.puts content
+            return
+          end
+
+          File.write(path, content)
+          warn "Exported to #{path}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    module Commands
+      # Exports a flow definition as a Mermaid flowchart (stdout or file).
+      class Graph < Dry::CLI::Command
+        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"
+
+        SHORT_DESCRIPTION = "Export a flow definition as a Mermaid diagram source, an image, or both."
+
+        if ARGV[0] == "graph"
+          desc LONG_DESCRIPTION
+        else
+          desc SHORT_DESCRIPTION
+        end
+
+        argument :flow_file,
+          required: true,
+          desc:     "Path to flow definition (.rb file)"
+        option :output,
+          aliases: ["-o"],
+          desc:    "Output file or a directory (default: stdout)"
+        option :format,
+          aliases: ["-f"],
+          default: "source",
+          values:  %w[source image both],
+          desc:    "Output format"
+        option :open,
+          aliases: ["-p"],
+          default: false,
+          type:    :boolean,
+          desc:    "Open the SVG in a system viewer"
+
+        # @param flow_file [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(flow_file:, **options)
+          definition = FlowLoader.load(flow_file)
+          source = Inquirex::Graph::MermaidExporter.new(definition).export
+          format = options[:format] || "source"
+          output = options[:output]
+
+          case format
+          when "source"
+            write_source(source, OutputPath.resolve(flow_file, output, ".mmd"))
+          when "image"
+            write_image(source, OutputPath.resolve_with_default(flow_file, output, ".png"), options[:open])
+          when "both"
+            write_source(source, OutputPath.resolve(flow_file, output, ".mmd"))
+            write_image(source, OutputPath.resolve_with_default(flow_file, output, ".png"), options[:open])
+          end
+        rescue Inquirex::TTY::Error => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def write_source(source, output_path)
+          unless output_path
+            $stdout.puts source
+            return
+          end
+          File.write(output_path, source)
+          warn "Diagram written to #{output_path}"
+        end
+
+        def write_image(source, output_path, open_file)
+          ensure_mermaid_cli_installed!
+
+          Tempfile.create(%w[inquirex-graph .mmd]) do |temp|
+            temp.write(source)
+            temp.flush
+            run_system_command!(
+              "mmdc -w 2000 -i #{Shellwords.escape(temp.path)} -o #{Shellwords.escape(output_path)}",
+              "Failed to generate image (mmdc)"
+            )
+          end
+
+          warn "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..."
+          installed = system("npm install -g @mermaid-js/mermaid-cli")
+          return if installed && command_available?("mmdc")
+
+          raise Inquirex::TTY::Error,
+            "Could not install mermaid-cli. Run: npm install -g @mermaid-js/mermaid-cli"
+        end
+
+        def open_image_file(filename)
+          run_system_command!(
+            "open #{Shellwords.escape(filename)}",
+            "Failed to open #{filename}"
+          )
+        end
+
+        def command_available?(command)
+          system("command -v #{command} > /dev/null 2>&1")
+        end
+
+        def run_system_command!(command, error_message)
+          raise Inquirex::TTY::Error, error_message unless system(command)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    module Commands
+      # Runs a flow definition interactively via TTY prompts and writes the
+      # collected answers (plus metadata) as JSON to stderr or a file.
+      class Run < Dry::CLI::Command
+        desc "Run a flow definition interactively"
+
+        argument :flow_file, required: true, desc: "Path to flow definition (.rb file)"
+        option :output, aliases: ["-o"], desc: "Write JSON results to this file instead of stderr"
+
+        # @param flow_file [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(flow_file:, **options)
+          engine = run_flow(flow_file)
+          json   = JSON.pretty_generate(build_result(flow_file, engine))
+
+          if options[:output]
+            File.write(options[:output], json)
+            puts "\nResults saved to #{options[:output]}"
+          else
+            $stderr.puts json # rubocop:disable Style/StderrPuts
+          end
+        rescue Inquirex::TTY::Error => e
+          error(e.message)
+          exit 1
+        rescue Inquirex::Errors::Error => e
+          error("Engine error: #{e.message}")
+          exit 1
+        end
+
+        private
+
+        # @param flow_file [String]
+        # @return [Inquirex::Engine]
+        def run_flow(flow_file)
+          load_dotenv!
+          definition = FlowLoader.load(flow_file)
+          engine     = Inquirex::Engine.new(definition)
+          renderer   = Renderer.new
+          adapter    = build_llm_adapter
+
+          show_banner(definition)
+
+          until engine.finished?
+            step = engine.current_step
+            next_step(engine.current_step_id, engine.history.length + 1)
+
+            if step.respond_to?(:llm_verb?) && step.llm_verb?
+              run_llm_step(engine, step, adapter, renderer)
+            elsif step.display?
+              renderer.render(step)
+              engine.advance
+            else
+              engine.answer(renderer.render(step))
+            end
+          end
+
+          engine
+        end
+
+        # Calls the LLM adapter for a clarify/describe/summarize/detour step,
+        # stores the result as the step's answer, and for clarify verbs splats
+        # extracted fields into top-level answers via Engine#prefill! so that
+        # downstream `skip_if not_empty(:key)` rules will fire.
+        def run_llm_step(engine, step, adapter, renderer)
+          renderer.thinking("🧠 Thinking — asking #{adapter_label(adapter)} to extract structured data…")
+          result = adapter.call(step, engine.answers)
+          engine.answer(result)
+          if step.verb == :clarify && result.is_a?(Hash)
+            engine.prefill!(result)
+            renderer.show_extraction(result)
+          else
+            puts "\n#{result.is_a?(String) ? result : JSON.pretty_generate(result)}\n"
+          end
+        rescue StandardError => e
+          error("LLM step #{step.id} failed: #{e.class}: #{e.message}")
+          raise
+        end
+
+        # Adapter preference order (first match wins):
+        #   INQUIREX_LLM_ADAPTER=null         → NullAdapter (forced offline)
+        #   INQUIREX_LLM_ADAPTER=anthropic    → AnthropicAdapter (fails if no key)
+        #   INQUIREX_LLM_ADAPTER=openai       → OpenAIAdapter (fails if no key)
+        #   ANTHROPIC_API_KEY present         → AnthropicAdapter
+        #   OPENAI_API_KEY present            → OpenAIAdapter
+        #   otherwise                         → NullAdapter
+        def build_llm_adapter
+          forced = ENV["INQUIREX_LLM_ADAPTER"].to_s.downcase
+          return Inquirex::LLM::NullAdapter.new      if forced == "null"
+          return Inquirex::LLM::AnthropicAdapter.new if forced == "anthropic"
+          return Inquirex::LLM::OpenAIAdapter.new    if forced == "openai"
+
+          if env_key?("ANTHROPIC_API_KEY") && defined?(Inquirex::LLM::AnthropicAdapter)
+            Inquirex::LLM::AnthropicAdapter.new
+          elsif env_key?("OPENAI_API_KEY") && defined?(Inquirex::LLM::OpenAIAdapter)
+            Inquirex::LLM::OpenAIAdapter.new
+          else
+            Inquirex::LLM::NullAdapter.new
+          end
+        end
+
+        def env_key?(name)
+          v = ENV.fetch(name, nil)
+          !v.nil? && !v.empty?
+        end
+
+        def adapter_label(adapter)
+          case adapter
+          when Inquirex::LLM::AnthropicAdapter then "Claude"
+          when Inquirex::LLM::OpenAIAdapter    then "GPT"
+          else "the null adapter"
+          end
+        rescue NameError
+          "the null adapter"
+        end
+
+        # Minimal .env loader. Walks up from the cwd and the flow file's
+        # directory, loading every .env found along the way. Later loads do
+        # not overwrite earlier values, and nothing overrides keys already
+        # set in the real environment.
+        def load_dotenv!
+          seen = {}
+          [Dir.pwd, File.dirname(File.expand_path(ARGV.last.to_s))].uniq.each do |start|
+            walk_ancestors(start).each do |dir|
+              path = File.join(dir, ".env")
+              next if seen[path] || !File.file?(path)
+
+              seen[path] = true
+              load_env_file(path)
+            end
+          end
+        end
+
+        def walk_ancestors(dir)
+          ancestors = []
+          current = File.expand_path(dir)
+          loop do
+            ancestors << current
+            parent = File.dirname(current)
+            break if parent == current
+
+            current = parent
+          end
+          ancestors
+        end
+
+        def load_env_file(path)
+          File.foreach(path) do |line|
+            next if line.strip.empty? || line.start_with?("#")
+
+            key, _, value = line.strip.partition("=")
+            next if key.empty?
+            # Preserve shell-set values, but fill in keys that are unset or
+            # set to the empty string.
+            next if ENV.key?(key) && !ENV[key].to_s.empty?
+
+            ENV[key] = value.gsub(/\A["']|["']\z/, "")
+          end
+        end
+
+        # @param definition [Inquirex::Definition]
+        # @return [void]
+        def show_banner(definition)
+          title = definition.meta&.fetch(:title, nil) || "Inquirex"
+          font  = ::TTY::Font.new(:standard)
+          title.split.each do |word|
+            puts pastel.bright_yellow(font.write(word))
+          end
+          sep(:green, "❚")
+        rescue StandardError
+          puts box(definition.meta&.fetch(:title, nil) || "Inquirex Wizard")
+        end
+
+        # @param flow_file [String]
+        # @param engine [Inquirex::Engine]
+        # @return [Hash]
+        def build_result(flow_file, engine)
+          {
+            flow_file:       flow_file,
+            path_taken:      engine.history,
+            answers:         engine.answers,
+            steps_completed: engine.history.length,
+            completed_at:    Time.now.iso8601
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    module Commands
+      # Validates a flow definition file: start step exists, all transition targets
+      # are known, and every step is reachable from the start step.
+      class Validate < Dry::CLI::Command
+        desc "Validate a flow definition file"
+
+        argument :flow_file, required: true, desc: "Path to flow definition (.rb file)"
+
+        # @param flow_file [String]
+        # @return [void]
+        def call(flow_file:, **)
+          definition = FlowLoader.load(flow_file)
+          errors     = validate_definition(definition)
+
+          if errors.empty?
+            print_success(definition)
+          else
+            print_errors(errors)
+            exit 1
+          end
+        rescue Inquirex::TTY::Error => e
+          warn "Error: #{e.message}"
+          exit 1
+        rescue Inquirex::Errors::Error => e
+          warn "Definition error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def print_success(definition)
+          puts "Flow definition is valid!"
+          puts "  ID:          #{definition.id || "(none)"}"
+          puts "  Version:     #{definition.version}"
+          puts "  Start step:  #{definition.start_step_id}"
+          puts "  Total steps: #{definition.step_ids.length}"
+          puts "  Steps:       #{definition.step_ids.join(", ")}"
+          print_meta(definition.meta) if definition.meta && !definition.meta.empty?
+        end
+
+        def print_meta(meta)
+          puts "  Title:    #{meta[:title]}"    if meta[:title]
+          puts "  Subtitle: #{meta[:subtitle]}" if meta[:subtitle]
+        end
+
+        def print_errors(errors)
+          warn "Flow definition has #{errors.length} error(s):"
+          errors.each { |e| warn "  - #{e}" }
+        end
+
+        def validate_definition(definition)
+          errors = []
+          validate_start_step(definition, errors)
+          validate_transition_targets(definition, errors)
+          validate_reachability(definition, errors)
+          errors
+        end
+
+        def validate_start_step(definition, errors)
+          return if definition.step_ids.include?(definition.start_step_id)
+
+          errors << "Start step :#{definition.start_step_id} not found in steps"
+        end
+
+        def validate_transition_targets(definition, errors)
+          definition.step_ids.each do |step_id|
+            step = definition.step(step_id)
+            step.transitions.each do |transition|
+              next if definition.step_ids.include?(transition.target)
+
+              errors << "Step :#{step_id} transitions to unknown step :#{transition.target}"
+            end
+          end
+        end
+
+        def validate_reachability(definition, errors)
+          reachable = find_reachable_steps(definition)
+          orphans   = definition.step_ids - reachable
+          orphans.each { |o| errors << "Step :#{o} is unreachable from :#{definition.start_step_id}" }
+        end
+
+        def find_reachable_steps(definition)
+          visited = Set.new
+          queue   = [definition.start_step_id]
+          known   = definition.step_ids
+
+          until queue.empty?
+            current = queue.shift
+            next if visited.include?(current)
+
+            visited << current
+            next unless known.include?(current)
+
+            definition.step(current).transitions.each do |t|
+              queue << t.target if known.include?(t.target)
+            end
+          end
+
+          visited.to_a
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    module Commands
+      # Prints inquirex-tty and inquirex gem versions to stdout.
+      class Version < Dry::CLI::Command
+        desc "Print version information"
+
+        # @param **_ [Hash] ignored options
+        # @return [void]
+        def call(**)
+          puts "inquirex-tty #{Inquirex::TTY::VERSION}"
+          puts "inquirex     #{Inquirex::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tty/commands.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Dry::CLI registry for inquirex-tty subcommands.
+    # UIHelper is mixed into every command so box/sep/next_step are available.
+    module Commands
+      extend Dry::CLI::Registry
+
+      ::Dry::CLI::Command.include(UIHelper)
+
+      register "run",        Run
+      register "graph",      Graph
+      register "export",     Export
+      register "validate",   Validate
+      register "version",    Version
+    end
+  end
+end

data/lib/inquirex/tty/flow_loader.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Loads a flow definition from a Ruby file by evaluating it in a top-level
+    # binding. The file is expected to call +Inquirex.define+ and return an
+    # +Inquirex::Definition+.
+    class FlowLoader
+      # @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
+      def self.load(path)
+        new(path).load
+      end
+
+      # @param path [String] path (will be expanded)
+      def initialize(path)
+        @path = File.expand_path(path)
+        validate_path!
+      end
+
+      # @return [Inquirex::Definition]
+      # @raise [Inquirex::TTY::Error] on syntax error
+      def load
+        content = File.read(@path)
+        # rubocop:disable Security/Eval
+        eval(content, TOPLEVEL_BINDING.dup, @path, 1)
+        # rubocop:enable Security/Eval
+      rescue SyntaxError => e
+        raise Inquirex::TTY::Error, "Syntax error in #{@path}: #{e.message}"
+      end
+
+      private
+
+      def validate_path!
+        raise Inquirex::TTY::Error, "File not found: #{@path}" unless File.exist?(@path)
+        raise Inquirex::TTY::Error, "Not a .rb file: #{@path}" unless @path.end_with?(".rb")
+      end
+    end
+  end
+end