flowengine-cli 0.1.0 → 0.1.2

data/examples/08_intake.rb

@@ -0,0 +1,33 @@
+# This is the first example in the README
+
+FlowEngine.define do
+  start :filing_status
+
+  step :filing_status do
+    type :single_select
+    question "What is your filing status?"
+    options %w[Single Married HeadOfHousehold]
+    transition to: :income_types
+  end
+
+  step :income_types do
+    type :multi_select
+    question "Select all income types that apply:"
+    options %w[W2 1099 Business Investment Rental]
+    transition to: :business_details, if_rule: contains(:income_types, "Business")
+    transition to: :summary
+  end
+
+  step :business_details do
+    type :number_matrix
+    question "How many of each business type?"
+    fields %w[LLC SCorp CCorp]
+    transition to: :summary
+  end
+
+  step :summary do
+    type :header
+    decorations("Success!")
+    question "Thank you for completing the intake!"
+  end
+end

data/justfile

@@ -2,10 +2,18 @@ set shell := ["bash", "-c"]
 
 set dotenv-load
 
+[no-exit-message]
+recipes:
+    @just --choose
+
 # Boot the app
 test:
+    @echo "Ensuring bundle install is up to date..."
     @bundle check ||  bundle install -j 12
+    @echo "Running specs..."
     @bundle exec rspec --format documentation
+    @echo "Running rubocop..."
+    @bundle exec rubocop
 
 # Setup Ruby dependencies
 setup-ruby:
@@ -29,15 +37,44 @@ setup: setup-node setup-ruby
 cli *ARGS:
     ./cli {{ARGS}}
 
-validate-valid-json:
-    ./cli validate-json -f VALID-JSON/sample.json -s VALID-JSON/schema.json
+# Run a flow interactively: just run examples/01_hello_world.rb
+run file *ARGS:
+    @bundle exec exe/flowengine-cli run {{file}} {{ARGS}}
+
+# Export a flow as a Mermaid diagram: just graph examples/07_loan_application.rb
+graph file *ARGS:
+    @bundle exec exe/flowengine-cli graph {{file}} {{ARGS}}
+
+# Validate a flow definition: just validate examples/04_event_registration.rb
+validate file:
+    @bundle exec exe/flowengine-cli validate {{file}}
 
+# List available example flows
+examples:
+    #!/usr/bin/env bash
+    if command fd>/dev/null 2>&1; then
+       fd --type file '.rb$' examples/
+    else
+       find examples -type f -name '*.rb'
+    fi
+    echo
+    echo "To run an example, type 'flow run examples/<example-file.rb>'"
+
+examples-list:
+
+# Formats minor syntax issues and writes the rest into a TODO file
 format:
     @bundle exec rubocop -a
     @bundle exec rubocop --auto-gen-config
 
+# Run all linters, in this case just rubocop
 lint: 
     @bundle exec rubocop
 
+# Generates YARD documentation into the ./doc folder, and opens ./doc/index.html
+doc:
+    @rake doc
+    @open doc/index.html
+
 check-all: lint test
 

data/lib/flowengine/cli/commands/graph.rb

@@ -3,6 +3,7 @@
 module FlowEngine
   module CLI
     module Commands
+      # Exports a flow definition as a Mermaid flowchart (stdout or file).
       class Graph < Dry::CLI::Command
         desc "Export a flow definition as a Mermaid diagram"
 
@@ -10,6 +11,9 @@ module FlowEngine
         option :output, aliases: ["-o"], desc: "Output file (default: stdout)"
         option :format, default: "mermaid", desc: "Output format (mermaid)"
 
+        # @param flow_file [String] path to the flow definition .rb file
+        # @param options [Hash] :output => path to write diagram, :format => "mermaid"
+        # @return [void]
         def call(flow_file:, **options)
           definition = FlowLoader.load(flow_file)
 

data/lib/flowengine/cli/commands/run.rb

@@ -7,45 +7,56 @@ require "tty-screen"
 module FlowEngine
   module CLI
     module Commands
+      # Runs a flow definition interactively via TTY prompts and writes the
+      # collected answers (and metadata) as JSON to stdout 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: "Output file for JSON results"
 
+        # @param flow_file [String] path to the flow definition .rb file
+        # @param options [Hash] :output => path to write JSON (optional)
+        # @return [void]
         def call(flow_file:, **options)
           engine = run_flow(flow_file)
           json_output = JSON.pretty_generate(build_result(flow_file, engine))
 
-          display_success("Flow completed!")
-          puts json_output
-
-          write_output(options[:output], json_output) if options[:output]
+          if options[:output]
+            write_output(options[:output], json_output)
+          else
+            $stderr.puts json_output # rubocop:disable Style/StderrPuts
+          end
         rescue FlowEngine::CLI::Error => e
-          display_error(e.message)
+          error(e.message)
           exit 1
         rescue FlowEngine::Error => e
-          display_error("Engine error: #{e.message}")
+          error("Engine error: #{e.message}")
           exit 1
         end
 
         private
 
+        # @param flow_file [String] path to flow definition
+        # @return [FlowEngine::Engine] engine after completion
         def run_flow(flow_file)
           definition = FlowLoader.load(flow_file)
           engine = FlowEngine::Engine.new(definition)
           renderer = Renderer.new
 
-          display_header("FlowEngine Interactive Wizard")
+          box("FlowEngine Interactive Wizard")
 
           until engine.finished?
-            display_step_indicator(engine.current_step_id, engine.history.length)
+            next_step(engine.current_step_id, engine.history.length)
             engine.answer(renderer.render(engine.current_step))
           end
 
           engine
         end
 
+        # @param flow_file [String] path used to load the flow
+        # @param engine [FlowEngine::Engine] completed engine
+        # @return [Hash] result hash with flow_file, path_taken, answers, etc.
         def build_result(flow_file, engine)
           {
             flow_file: flow_file,
@@ -56,30 +67,13 @@ module FlowEngine
           }
         end
 
+        # @param path [String] output file path
+        # @param json_output [String] JSON string to write
+        # @return [void]
         def write_output(path, json_output)
           File.write(path, json_output)
           puts "\nResults saved to #{path}"
         end
-
-        def display_header(text)
-          width = [TTY::Screen.width, 80].min
-          puts TTY::Box.frame(text, width: width, padding: 1, align: :center, border: :thick)
-        end
-
-        def display_step_indicator(step_id, step_number)
-          puts "\n  Step #{step_number}: #{step_id}"
-          puts "  #{"─" * 40}"
-        end
-
-        def display_success(text)
-          width = [TTY::Screen.width, 80].min
-          puts TTY::Box.frame(text, width: width, padding: 1, align: :center, title: { top_left: " SUCCESS " })
-        end
-
-        def display_error(text)
-          width = [TTY::Screen.width, 80].min
-          puts TTY::Box.frame(text, width: width, padding: 1, align: :center, title: { top_left: " ERROR " })
-        end
       end
     end
   end

data/lib/flowengine/cli/commands/validate_flow.rb

@@ -3,11 +3,16 @@
 module FlowEngine
   module CLI
     module Commands
+      # Validates a flow definition file: start step exists, transitions point to
+      # known steps, and all steps are reachable from the start step.
       class ValidateFlow < 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] path to the flow definition .rb file
+        # @param **_ [Hash] ignored options
+        # @return [void]
         def call(flow_file:, **)
           definition = FlowLoader.load(flow_file)
           errors = validate_definition(definition)
@@ -28,6 +33,8 @@ module FlowEngine
 
         private
 
+        # @param definition [FlowEngine::Definition]
+        # @return [void]
         def print_success(definition)
           puts "Flow definition is valid!"
           puts "  Start step: #{definition.start_step_id}"
@@ -35,11 +42,15 @@ module FlowEngine
           puts "  Steps: #{definition.step_ids.join(", ")}"
         end
 
+        # @param errors [Array<String>]
+        # @return [void]
         def print_errors(errors)
           warn "Flow definition has errors:"
           errors.each { |e| warn "  - #{e}" }
         end
 
+        # @param definition [FlowEngine::Definition]
+        # @return [Array<String>] list of error messages
         def validate_definition(definition)
           errors = []
 
@@ -50,12 +61,18 @@ module FlowEngine
           errors
         end
 
+        # @param definition [FlowEngine::Definition]
+        # @param errors [Array<String>] mutated with new errors
+        # @return [void]
         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
 
+        # @param definition [FlowEngine::Definition]
+        # @param errors [Array<String>] mutated with new errors
+        # @return [void]
         def validate_transition_targets(definition, errors)
           definition.step_ids.each do |step_id|
             step = definition.step(step_id)
@@ -67,6 +84,9 @@ module FlowEngine
           end
         end
 
+        # @param definition [FlowEngine::Definition]
+        # @param errors [Array<String>] mutated with new errors
+        # @return [void]
         def validate_reachability(definition, errors)
           reachable = find_reachable_steps(definition)
           orphans = definition.step_ids - reachable
@@ -76,6 +96,8 @@ module FlowEngine
           end
         end
 
+        # @param definition [FlowEngine::Definition]
+        # @return [Array<Symbol>] step ids reachable from start
         def find_reachable_steps(definition)
           visited = Set.new
           queue = [definition.start_step_id]
@@ -94,6 +116,10 @@ module FlowEngine
           visited.to_a
         end
 
+        # @param step [FlowEngine::Node]
+        # @param known_ids [Array<Symbol>]
+        # @param queue [Array] mutated with transition targets
+        # @return [void]
         def enqueue_transitions(step, known_ids, queue)
           step.transitions.each do |t|
             queue << t.target if known_ids.include?(t.target)

data/lib/flowengine/cli/commands/version.rb

@@ -3,9 +3,12 @@
 module FlowEngine
   module CLI
     module Commands
+      # Prints flowengine-cli and flowengine gem versions to stdout.
       class Version < Dry::CLI::Command
         desc "Print version information"
 
+        # @param **_ [Hash] ignored options
+        # @return [void]
         def call(**)
           puts "flowengine-cli #{FlowEngine::CLI::VERSION}"
           puts "flowengine #{FlowEngine::VERSION}"

data/lib/flowengine/cli/commands.rb

@@ -5,12 +5,16 @@ require_relative "commands/run"
 require_relative "commands/graph"
 require_relative "commands/validate_flow"
 require_relative "commands/version"
+require_relative "ui_helper"
 
 module FlowEngine
   module CLI
+    # Dry::CLI registry for flowengine-cli subcommands: run, graph, validate, version.
     module Commands
       extend Dry::CLI::Registry
 
+      ::Dry::CLI::Command.include(UIHelper)
+
       register "run", Run
       register "graph", Graph
       register "validate", ValidateFlow

data/lib/flowengine/cli/flow_loader.rb

@@ -2,16 +2,27 @@
 
 module FlowEngine
   module CLI
+    # Loads a flow definition from a Ruby file by evaluating it in a top-level
+    # binding. Expects the file to define a flow via FlowEngine.define and
+    # return a FlowEngine::Definition.
     class FlowLoader
+      # Load a flow definition from a file.
+      # @param path [String] path to a .rb flow definition file
+      # @return [FlowEngine::Definition] the evaluated definition
+      # @raise [FlowEngine::CLI::Error] if file is missing, not .rb, or has syntax errors
       def self.load(path)
         new(path).load
       end
 
+      # @param path [String] path to the flow definition file (will be expanded)
       def initialize(path)
         @path = File.expand_path(path)
         validate_path!
       end
 
+      # Evaluates the file and returns the resulting definition.
+      # @return [FlowEngine::Definition]
+      # @raise [FlowEngine::CLI::Error] on syntax error
       def load
         content = File.read(@path)
         # Evaluate in a clean binding that has FlowEngine available
@@ -24,6 +35,7 @@ module FlowEngine
 
       private
 
+      # @raise [FlowEngine::CLI::Error] if path does not exist or does not end with .rb
       def validate_path!
         raise FlowEngine::CLI::Error, "File not found: #{@path}" unless File.exist?(@path)
         raise FlowEngine::CLI::Error, "Not a .rb file: #{@path}" unless @path.end_with?(".rb")

data/lib/flowengine/cli/renderer.rb

@@ -1,16 +1,27 @@
 # frozen_string_literal: true
 
 require "tty-prompt"
+require_relative "ui_helper"
 
 module FlowEngine
   module CLI
+    # Renders flow steps as TTY prompts. Dispatches to a type-specific renderer
+    # (e.g. +render_multi_select+, +render_single_select+) or falls back to
+    # +render_text+ for unknown node types.
     class Renderer
+      # @return [TTY::Prompt] the TTY prompt instance used for input
       attr_reader :prompt
 
+      include ::FlowEngine::CLI::UIHelper
+
+      # @param prompt [TTY::Prompt] prompt instance (default: new TTY::Prompt)
       def initialize(prompt: TTY::Prompt.new)
         @prompt = prompt
       end
 
+      # Renders a single step node and returns the user's answer.
+      # @param node [FlowEngine::Node] the current step node from the flow definition
+      # @return [Object] answer value (String, Integer, Boolean, Array, Hash, or nil)
       def render(node)
         method_name = :"render_#{node.type}"
 
@@ -23,14 +34,20 @@ module FlowEngine
 
       private
 
+      # @param node [FlowEngine::Node] multi_select step
+      # @return [Array<String>]
       def render_multi_select(node)
         prompt.multi_select(node.question, node.options, min: 1)
       end
 
+      # @param node [FlowEngine::Node] single_select step
+      # @return [String]
       def render_single_select(node)
         prompt.select(node.question, node.options)
       end
 
+      # @param node [FlowEngine::Node] number_matrix step
+      # @return [Hash<String, Integer>]
       def render_number_matrix(node)
         puts "\n#{node.question}\n\n"
         result = {}
@@ -40,21 +57,44 @@ module FlowEngine
         result
       end
 
+      # @param node [FlowEngine::Node] text step
+      # @return [String, nil]
       def render_text(node)
         prompt.ask(node.question)
       end
 
+      # @param node [FlowEngine::Node] number step
+      # @return [Integer, nil]
       def render_number(node)
         prompt.ask(node.question, convert: :int)
       end
 
+      # @param node [FlowEngine::Node] boolean step
+      # @return [Boolean]
       def render_boolean(node) # rubocop:disable Naming/PredicateMethod
         prompt.yes?(node.question)
       end
 
+      # @param node [FlowEngine::Node] display step (informational, no answer)
+      # @return [nil]
       def render_display(node)
         puts "\n#{node.question}\n"
         prompt.keypress("Press any key to continue...")
+        sep(:green, "━")
+        nil
+      end
+
+      # Renders a header node with a title and a separator.
+      # @param node [FlowEngine::Node] header step (optional decorations)
+      # @return [nil]
+      def render_header(node)
+        title = node.respond_to?(:decorations) ? node.decorations : nil
+        opts = {}
+        opts[:title] = { style: { top_left: title } } if title
+        puts box(node.question, bg: :blue, fg: :white, **opts)
+        puts node.question
+        prompt.keypress("Press any key to continue...")
+        sep(:green, "━")
         nil
       end
     end

data/lib/flowengine/cli/ui_helper.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+
+require "forwardable"
+require "tty-box"
+require "tty-screen"
+require "pastel"
+
+module FlowEngine
+  module CLI
+    # Mixin that provides 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 for colored output
+        def pastel
+          @pastel ||= Pastel.new
+        end
+
+        def included(base)
+          base.extend(Forwardable)
+          # Forwardable needs an accessor (method returning the target).
+          # :TTY::Box / :TTY::Screen are not valid method names on the instance.
+          base.define_method(:tty_box) { ::TTY::Box }
+          base.define_method(:tty_screen) { ::TTY::Screen }
+          base.define_method(:pastel) { ::FlowEngine::CLI::UIHelper.pastel }
+
+          # TTY::Box uses :warn, not :warning
+          %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.
+            # @param text [String] content to display
+            # @param title [String, nil] optional top-left title
+            # @param bg [Symbol] background color (e.g. :green, :blue)
+            # @param fg [Symbol] foreground color (e.g. :white)
+            # @return [void]
+            def box(text, title: nil, bg: :green, fg: :white) # rubocop:disable Naming/MethodParameterName
+              width = [width(), 80].min
+              args = {
+                width: width,
+                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 line and separator.
+            # @param step_id [Symbol, String] current step identifier
+            # @param step_number [Integer] 1-based step index
+            # @return [void]
+            def next_step(step_id, step_number)
+              puts pastel.yellow("Step #{step_number}: #{step_id}")
+              sep(:yellow, "━")
+            end
+
+            # Print a horizontal separator line in the given color.
+            # @param color [Symbol] Pastel color (e.g. :yellow, :green)
+            # @param char [String] character to repeat (default "▪")
+            # @return [void]
+            def sep(color = :yellow, char = "▪")
+              puts pastel.send(color, (char * 80).to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Metrics/MethodLength, Metrics/AbcSize

data/lib/flowengine/cli/version.rb

@@ -2,6 +2,7 @@
 
 module FlowEngine
   module CLI
-    VERSION = "0.1.0"
+    # Semantic version of the flowengine-cli gem.
+    VERSION = "0.1.2"
   end
 end

data/lib/flowengine/cli.rb

@@ -7,7 +7,10 @@ require_relative "cli/renderer"
 require_relative "cli/commands"
 
 module FlowEngine
+  # Terminal UI adapter for flowengine: runs flows interactively via Dry::CLI
+  # and TTY components, and supports graph export and flow validation.
   module CLI
+    # Raised when flowengine-cli encounters a load, validation, or runtime error.
     class Error < StandardError; end
   end
 end