flowengine-cli 0.1.0 → 0.1.2

data/Rakefile

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'timeout'
-require 'yard'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+require "yard"
 
 def shell(*args)
-  puts "running: #{args.join(' ')}"
-  system(args.join(' '))
+  puts "running: #{args.join(" ")}"
+  system(args.join(" "))
 end
 
 task :clean do
-  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
 end
 
 task gem: [:build] do
-  shell('gem install pkg/*')
+  shell("gem install pkg/*")
 end
 
 task permissions: [:clean] do
@@ -24,12 +24,11 @@ task permissions: [:clean] do
 end
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE.txt)
-  t.options.unshift('--title', '"FlowEngine CLI is the CLI for validating FlowEngine in the Terminal"')
-  t.after = -> { exec('open doc/index.html') } if RUBY_PLATFORM =~ /darwin/
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine CLI is the CLI for validating FlowEngine in the Terminal"')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end
 
-
 task build: :permissions
 
 RSpec::Core::RakeTask.new(:spec)

data/examples/01_hello_world.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Example 1: Hello World
+#
+# The simplest possible flow — three linear steps, no branching.
+# Demonstrates: text input, number input, display output.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/01_hello_world.rb
+
+FlowEngine.define do
+  start :name
+
+  step :name do
+    type :text
+    question "What is your name?"
+    transition to: :age
+  end
+
+  step :age do
+    type :number
+    question "How old are you?"
+    transition to: :farewell
+  end
+
+  step :farewell do
+    type :display
+    question "Thanks for stopping by! Have a great day."
+  end
+end

data/examples/02_yes_or_no.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Example 2: Yes or No
+#
+# A single boolean branch. Answering "yes" takes a detour;
+# answering "no" goes straight to the end.
+# Demonstrates: boolean step, equals rule, simple branching.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/02_yes_or_no.rb
+
+FlowEngine.define do
+  start :has_pet
+
+  step :has_pet do
+    type :boolean
+    question "Do you have a pet?"
+    transition to: :pet_name, if_rule: equals(:has_pet, true)
+    transition to: :done
+  end
+
+  step :pet_name do
+    type :text
+    question "What is your pet's name?"
+    transition to: :done
+  end
+
+  step :done do
+    type :display
+    question "All done! Thanks for answering."
+  end
+end

data/examples/03_food_preferences.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Example 3: Food Preferences
+#
+# Multiple independent branches from a single multi_select step.
+# Each selection may activate a different follow-up question.
+# Demonstrates: multi_select, contains rule, multiple transitions.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/03_food_preferences.rb
+
+FlowEngine.define do
+  start :diet
+
+  step :diet do
+    type :multi_select
+    question "Which food categories do you enjoy?"
+    options %w[Meat Seafood Vegetarian Vegan Dessert]
+    transition to: :meat_preference, if_rule: contains(:diet, "Meat")
+    transition to: :seafood_preference, if_rule: contains(:diet, "Seafood")
+    transition to: :dessert_preference, if_rule: contains(:diet, "Dessert")
+    transition to: :summary
+  end
+
+  step :meat_preference do
+    type :single_select
+    question "What is your favorite type of meat?"
+    options %w[Beef Chicken Pork Lamb]
+    transition to: :seafood_preference, if_rule: contains(:diet, "Seafood")
+    transition to: :dessert_preference, if_rule: contains(:diet, "Dessert")
+    transition to: :summary
+  end
+
+  step :seafood_preference do
+    type :single_select
+    question "What is your favorite type of seafood?"
+    options %w[Salmon Tuna Shrimp Lobster Crab]
+    transition to: :dessert_preference, if_rule: contains(:diet, "Dessert")
+    transition to: :summary
+  end
+
+  step :dessert_preference do
+    type :single_select
+    question "What is your favorite dessert?"
+    options %w[Cake IceCream Pie Cookies Fruit]
+    transition to: :summary
+  end
+
+  step :summary do
+    type :display
+    question "Thanks! We've noted your food preferences."
+  end
+end

data/examples/04_event_registration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Example 4: Event Registration
+#
+# Two levels of conditional logic. The ticket type determines one
+# branch, and within VIP there's a further branch based on
+# whether the guest wants a plus-one.
+# Demonstrates: single_select, boolean, equals rule, two-level branching.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/04_event_registration.rb
+
+FlowEngine.define do
+  start :attendee_name
+
+  step :attendee_name do
+    type :text
+    question "What is your full name?"
+    transition to: :ticket_type
+  end
+
+  step :ticket_type do
+    type :single_select
+    question "Select your ticket type:"
+    options %w[General VIP Speaker]
+    transition to: :vip_options, if_rule: equals(:ticket_type, "VIP")
+    transition to: :talk_title, if_rule: equals(:ticket_type, "Speaker")
+    transition to: :dietary
+  end
+
+  # --- VIP branch (level 1) ---
+
+  step :vip_options do
+    type :boolean
+    question "Would you like to bring a plus-one?"
+    transition to: :plus_one_name, if_rule: equals(:vip_options, true)
+    transition to: :dietary
+  end
+
+  # VIP plus-one sub-branch (level 2)
+  step :plus_one_name do
+    type :text
+    question "What is your plus-one's name?"
+    transition to: :dietary
+  end
+
+  # --- Speaker branch (level 1) ---
+
+  step :talk_title do
+    type :text
+    question "What is the title of your talk?"
+    transition to: :av_needs
+  end
+
+  # Speaker AV sub-branch (level 2)
+  step :av_needs do
+    type :multi_select
+    question "What A/V equipment do you need?"
+    options %w[Projector Microphone Whiteboard ScreenShare None]
+    transition to: :dietary
+  end
+
+  # --- Common path ---
+
+  step :dietary do
+    type :single_select
+    question "Any dietary restrictions?"
+    options %w[None Vegetarian Vegan GlutenFree Halal Kosher]
+    transition to: :confirmation
+  end
+
+  step :confirmation do
+    type :display
+    question "You're registered! See you at the event."
+  end
+end

data/examples/05_job_application.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Example 5: Job Application Intake
+#
+# Two levels of branching with composed rules (all/any).
+# The role determines the first branch; experience level and
+# specific answers open deeper sub-branches.
+# Demonstrates: all(), any(), greater_than, contains, two-level branching.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/05_job_application.rb
+
+FlowEngine.define do
+  start :applicant_name
+
+  step :applicant_name do
+    type :text
+    question "What is your full name?"
+    transition to: :role
+  end
+
+  step :role do
+    type :single_select
+    question "Which role are you applying for?"
+    options %w[Engineering Design ProductManagement Sales]
+    transition to: :engineering_skills, if_rule: equals(:role, "Engineering")
+    transition to: :design_portfolio, if_rule: equals(:role, "Design")
+    transition to: :years_experience
+  end
+
+  # --- Engineering branch (level 1) ---
+
+  step :engineering_skills do
+    type :multi_select
+    question "Select your primary skills:"
+    options %w[Ruby Python JavaScript Go Rust Java]
+    transition to: :years_experience
+  end
+
+  # --- Design branch (level 1) ---
+
+  step :design_portfolio do
+    type :text
+    question "Please provide a link to your portfolio:"
+    transition to: :years_experience
+  end
+
+  # --- Common: experience (feeds level 2 branching) ---
+
+  step :years_experience do
+    type :number
+    question "How many years of professional experience do you have?"
+    transition to: :leadership_experience, if_rule: greater_than(:years_experience, 7)
+    transition to: :education
+  end
+
+  # Level 2 branch: senior applicants
+  step :leadership_experience do
+    type :boolean
+    question "Have you managed a team of 5 or more people?"
+    transition to: :management_style, if_rule: equals(:leadership_experience, true)
+    transition to: :education
+  end
+
+  # Level 2 sub-branch: managers
+  step :management_style do
+    type :single_select
+    question "How would you describe your management style?"
+    options %w[Collaborative Directive Coaching Delegative]
+    transition to: :education
+  end
+
+  step :education do
+    type :single_select
+    question "What is your highest level of education?"
+    options %w[HighSchool Bachelors Masters PhD Bootcamp SelfTaught]
+    transition to: :availability
+  end
+
+  step :availability do
+    type :single_select
+    question "When can you start?"
+    options %w[Immediately TwoWeeks OneMonth ThreeMonths]
+    transition to: :referral
+  end
+
+  step :referral do
+    type :boolean
+    question "Were you referred by a current employee?"
+    transition to: :referral_name, if_rule: equals(:referral, true)
+    transition to: :thanks
+  end
+
+  step :referral_name do
+    type :text
+    question "Who referred you?"
+    transition to: :thanks
+  end
+
+  step :thanks do
+    type :display
+    question "Application submitted! We'll be in touch within 5 business days."
+  end
+end

data/examples/06_health_assessment.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Example 6: Health Risk Assessment
+#
+# Three levels of conditional branching with composed rules.
+#
+# Level 1: Lifestyle choices branch into exercise, smoking, or diet paths.
+# Level 2: Within exercise, intensity level opens a sub-branch.
+#          Within smoking, pack count opens a sub-branch.
+# Level 3: Heavy smokers with additional risk factors get a deeper follow-up.
+#
+# Demonstrates: all(), any(), greater_than, less_than, contains, equals,
+#               three-level deep conditional logic.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/06_health_assessment.rb
+
+FlowEngine.define do
+  start :patient_info
+
+  step :patient_info do
+    type :text
+    question "Patient name and date of birth (e.g., Jane Doe, 1985-03-15):"
+    transition to: :lifestyle
+  end
+
+  step :lifestyle do
+    type :multi_select
+    question "Select all that apply to your lifestyle:"
+    options %w[Exercise Smoking Alcohol HighStress PoorDiet]
+    transition to: :exercise_frequency, if_rule: contains(:lifestyle, "Exercise")
+    transition to: :smoking_details, if_rule: contains(:lifestyle, "Smoking")
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # ============================================================
+  # LEVEL 1 — Exercise branch
+  # ============================================================
+
+  step :exercise_frequency do
+    type :number
+    question "How many days per week do you exercise?"
+    transition to: :exercise_intensity, if_rule: greater_than(:exercise_frequency, 3)
+    transition to: :smoking_details, if_rule: contains(:lifestyle, "Smoking")
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # LEVEL 2 — Intense exerciser sub-branch
+  step :exercise_intensity do
+    type :single_select
+    question "What best describes your typical workout intensity?"
+    options %w[Moderate Vigorous Extreme]
+    transition to: :injury_history, if_rule: equals(:exercise_intensity, "Extreme")
+    transition to: :smoking_details, if_rule: contains(:lifestyle, "Smoking")
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # LEVEL 3 — Extreme exerciser injury check
+  step :injury_history do
+    type :boolean
+    question "Have you had any exercise-related injuries in the past year?"
+    transition to: :smoking_details, if_rule: contains(:lifestyle, "Smoking")
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # ============================================================
+  # LEVEL 1 — Smoking branch
+  # ============================================================
+
+  step :smoking_details do
+    type :number
+    question "How many packs per day do you smoke?"
+    transition to: :smoking_duration, if_rule: greater_than(:smoking_details, 1)
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # LEVEL 2 — Heavy smoker sub-branch
+  step :smoking_duration do
+    type :number
+    question "How many years have you been smoking?"
+    transition to: :smoking_cessation, if_rule: all(
+      greater_than(:smoking_duration, 10),
+      greater_than(:smoking_details, 1)
+    )
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # LEVEL 3 — Long-term heavy smoker: cessation counseling
+  step :smoking_cessation do
+    type :boolean
+    question "Have you tried a cessation program before?"
+    transition to: :cessation_details, if_rule: equals(:smoking_cessation, true)
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  step :cessation_details do
+    type :text
+    question "Please describe what programs you tried and when:"
+    transition to: :diet_details, if_rule: contains(:lifestyle, "PoorDiet")
+    transition to: :sleep_quality
+  end
+
+  # ============================================================
+  # LEVEL 1 — Diet branch
+  # ============================================================
+
+  step :diet_details do
+    type :multi_select
+    question "Which of these describe your typical diet?"
+    options %w[HighSugar HighSodium LowFiber SkipsMeals FastFood ProcessedFoods]
+    transition to: :sleep_quality
+  end
+
+  # ============================================================
+  # Common tail
+  # ============================================================
+
+  step :sleep_quality do
+    type :single_select
+    question "How would you rate your sleep quality?"
+    options %w[Excellent Good Fair Poor]
+    transition to: :mental_health, if_rule: any(
+      equals(:sleep_quality, "Fair"),
+      equals(:sleep_quality, "Poor")
+    )
+    transition to: :family_history
+  end
+
+  step :mental_health do
+    type :multi_select
+    question "Do any of these apply to you?"
+    options %w[Anxiety Depression Insomnia ChronicFatigue None]
+    transition to: :family_history
+  end
+
+  step :family_history do
+    type :multi_select
+    question "Select any conditions that run in your family:"
+    options %w[HeartDisease Diabetes Cancer Hypertension None]
+    transition to: :risk_summary
+  end
+
+  step :risk_summary do
+    type :display
+    question "Assessment complete. Your responses have been recorded for review by your provider."
+  end
+end

data/examples/07_loan_application.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+# Example 7: Loan Application
+#
+# Three levels of conditional branching with composed rules (all, any).
+#
+# Level 1: Loan type (Personal / Mortgage / Business) splits into different paths.
+# Level 2: Within Mortgage, property type triggers sub-branches.
+#          Within Business, revenue level triggers sub-branches.
+# Level 3: High-value mortgage applicants with specific conditions get
+#          additional scrutiny. Low-revenue startups get a different path
+#          than established businesses.
+#
+# Demonstrates: all(), any(), greater_than, less_than, equals, contains,
+#               three-level deep conditional logic, number_matrix.
+#
+# Run:  bundle exec exe/flowengine-cli run examples/07_loan_application.rb
+
+FlowEngine.define do
+  start :applicant_info
+
+  step :applicant_info do
+    type :text
+    question "Full legal name:"
+    transition to: :loan_type
+  end
+
+  step :loan_type do
+    type :single_select
+    question "What type of loan are you applying for?"
+    options %w[Personal Mortgage Business]
+    transition to: :personal_amount, if_rule: equals(:loan_type, "Personal")
+    transition to: :mortgage_property, if_rule: equals(:loan_type, "Mortgage")
+    transition to: :business_info, if_rule: equals(:loan_type, "Business")
+  end
+
+  # ============================================================
+  # LEVEL 1 — Personal loan (simple path)
+  # ============================================================
+
+  step :personal_amount do
+    type :number
+    question "How much would you like to borrow (in dollars)?"
+    transition to: :personal_purpose
+  end
+
+  step :personal_purpose do
+    type :single_select
+    question "What is the primary purpose of this loan?"
+    options %w[DebtConsolidation HomeImprovement Medical Travel Education Other]
+    transition to: :credit_check
+  end
+
+  # ============================================================
+  # LEVEL 1 — Mortgage branch
+  # ============================================================
+
+  step :mortgage_property do
+    type :single_select
+    question "What type of property is this for?"
+    options %w[SingleFamily Condo Townhouse MultiFamily Commercial]
+    transition to: :mortgage_amount
+  end
+
+  step :mortgage_amount do
+    type :number
+    question "What is the estimated property value (in dollars)?"
+    transition to: :mortgage_high_value, if_rule: greater_than(:mortgage_amount, 750_000)
+    transition to: :down_payment
+  end
+
+  # LEVEL 2 — High-value mortgage
+  step :mortgage_high_value do
+    type :boolean
+    question "Will this be your primary residence?"
+    transition to: :jumbo_review, if_rule: all(
+      equals(:mortgage_high_value, false),
+      greater_than(:mortgage_amount, 750_000)
+    )
+    transition to: :down_payment
+  end
+
+  # LEVEL 3 — Investment property jumbo loan
+  step :jumbo_review do
+    type :number_matrix
+    question "Provide details about your existing properties:"
+    fields %w[OwnedProperties RentalProperties MortgagesOwed]
+    transition to: :down_payment
+  end
+
+  step :down_payment do
+    type :number
+    question "How much is your down payment (in dollars)?"
+    transition to: :credit_check
+  end
+
+  # ============================================================
+  # LEVEL 1 — Business loan branch
+  # ============================================================
+
+  step :business_info do
+    type :text
+    question "Business name and EIN:"
+    transition to: :business_type
+  end
+
+  step :business_type do
+    type :single_select
+    question "Business structure:"
+    options %w[SoleProprietor LLC SCorp CCorp Partnership]
+    transition to: :annual_revenue
+  end
+
+  step :annual_revenue do
+    type :number
+    question "What is your annual revenue (in dollars)?"
+    transition to: :startup_details, if_rule: less_than(:annual_revenue, 100_000)
+    transition to: :established_details, if_rule: greater_than(:annual_revenue, 500_000)
+    transition to: :business_loan_amount
+  end
+
+  # LEVEL 2 — Startup path
+  step :startup_details do
+    type :number
+    question "How many months has the business been operating?"
+    transition to: :startup_funding, if_rule: less_than(:startup_details, 12)
+    transition to: :business_loan_amount
+  end
+
+  # LEVEL 3 — Very new startup
+  step :startup_funding do
+    type :multi_select
+    question "What funding sources have you used so far?"
+    options %w[PersonalSavings FriendsFamily AngelInvestor VentureCapital Grant CreditCards None]
+    transition to: :business_loan_amount
+  end
+
+  # LEVEL 2 — Established business path
+  step :established_details do
+    type :number_matrix
+    question "Provide financial details:"
+    fields %w[Employees AnnualExpenses OutstandingDebt]
+    transition to: :established_expansion, if_rule: all(
+      greater_than(:annual_revenue, 500_000),
+      any(
+        equals(:business_type, "CCorp"),
+        equals(:business_type, "SCorp")
+      )
+    )
+    transition to: :business_loan_amount
+  end
+
+  # LEVEL 3 — Corp expansion review
+  step :established_expansion do
+    type :multi_select
+    question "What will the loan fund?"
+    options %w[Hiring Equipment RealEstate Acquisition Marketing RAndD]
+    transition to: :business_loan_amount
+  end
+
+  step :business_loan_amount do
+    type :number
+    question "How much funding are you requesting (in dollars)?"
+    transition to: :credit_check
+  end
+
+  # ============================================================
+  # Common tail
+  # ============================================================
+
+  step :credit_check do
+    type :boolean
+    question "Do you authorize a credit check?"
+    transition to: :review, if_rule: equals(:credit_check, true)
+    transition to: :declined
+  end
+
+  step :declined do
+    type :display
+    question "A credit check is required to proceed. Your application has been saved as a draft."
+  end
+
+  step :review do
+    type :display
+    question "Application submitted! You will receive a decision within 3-5 business days."
+  end
+end