flowengine-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae12fe144b1694228a1fcdaeccab821dbbb4667be164bc01cb2ffd7111a7cba1
+  data.tar.gz: 45e96c201167069000eea870f8801777c01c561570cb029fef3c428fc9919609
+SHA512:
+  metadata.gz: 3d8f0f0c29129144bdd700e621307b17df356a460c85468806efab0d683409b2fbcdc7da34bec9868b22d0394ab3d503ead856fd78e3ae837292a8a760b08c32
+  data.tar.gz: dcb8897fd96a7f5841006937e3448bc913e126829ab772c57967c2b2741440b5e5e708314281eb43a3d4b8b742489c1315f1426dcdb197b65b0ec3087ae56a73

data/.envrc

@@ -0,0 +1 @@
+PATH_add exe

data/.rubocop_todo.yml

@@ -0,0 +1,7 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-02-27 03:54:38 UTC using RuboCop version 1.85.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konstantin Gredeskoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,554 @@
+# FlowEngine CLI
+
+[![RSpec](https://github.com/kigster/flowengine-cli/actions/workflows/rspec.yml/badge.svg)](https://github.com/kigster/flowengine-cli/actions/workflows/rspec.yml) [![RuboCop](https://github.com/kigster/flowengine-cli/actions/workflows/rubocop.yml/badge.svg)](https://github.com/kigster/flowengine-cli/actions/workflows/rubocop.yml)
+
+Terminal-based interactive wizard runner for [FlowEngine](https://github.com/kigster/flowengine) flows. Define your flow once, run it in the terminal with rich TTY prompts, export Mermaid diagrams, and validate flow definitions -- all from the command line.
+
+FlowEngine CLI is a UI adapter that sits on top of the pure-Ruby `flowengine` core gem. The core gem knows nothing about terminals, databases, or web frameworks. This gem provides the terminal interface.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "flowengine-cli"
+```
+
+Or install directly:
+
+```bash
+gem install flowengine-cli
+```
+
+### Requirements
+
+- Ruby >= 4.0.1
+- [flowengine](https://github.com/kigster/flowengine) ~> 0.1
+
+## Quick Start
+
+### 1. Define a flow
+
+Create a file called `intake.rb`:
+
+```ruby
+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 :display
+    question "Thank you for completing the intake!"
+  end
+end
+```
+
+### 2. Run it
+
+```bash
+flowengine-cli run intake.rb
+```
+
+The CLI walks you through each step interactively, rendering the appropriate TTY prompt for each step type. When complete, it outputs the collected answers as JSON:
+
+```json
+{
+  "flow_file": "intake.rb",
+  "path_taken": ["filing_status", "income_types", "business_details", "summary"],
+  "answers": {
+    "filing_status": "Married",
+    "income_types": ["W2", "Business"],
+    "business_details": { "LLC": 2, "SCorp": 1, "CCorp": 0 }
+  },
+  "steps_completed": 4,
+  "completed_at": "2026-02-26T20:15:00-08:00"
+}
+```
+
+### 3. Save results to a file
+
+```bash
+flowengine-cli run intake.rb -o results.json
+```
+
+## Commands
+
+### `run` -- Interactive Wizard
+
+```bash
+flowengine-cli run <flow_file.rb> [-o output.json]
+```
+
+Loads a flow definition, presents each step as an interactive terminal prompt, and outputs the collected answers as JSON when complete.
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `flow_file` | Yes | Path to a `.rb` file containing a `FlowEngine.define` block |
+
+**Options:**
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output` | `-o` | Write JSON results to this file |
+
+**What happens at runtime:**
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                FlowEngine Interactive Wizard                   ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+  Step 1: filing_status
+  ────────────────────────────────────
+  What is your filing status? (Use ↑/↓ arrow keys, press Enter to select)
+  > Single
+    Married
+    HeadOfHousehold
+
+  Step 2: income_types
+  ────────────────────────────────────
+  Select all income types that apply: (Use ↑/↓ arrow keys, press Space to select)
+    ◯ W2
+  > ◉ 1099
+    ◉ Business
+    ◯ Investment
+    ◯ Rental
+
+  Step 3: business_details
+  ────────────────────────────────────
+  How many of each business type?
+
+    LLC: 2
+    SCorp: 1
+    CCorp: 0
+
+┌ SUCCESS ─────────────────────────────────────────────────────────┐
+│                      Flow completed!                             │
+└──────────────────────────────────────────────────────────────────┘
+{ ... JSON output ... }
+```
+
+---
+
+### `graph` -- Export Mermaid Diagram
+
+```bash
+flowengine-cli graph <flow_file.rb> [-o diagram.mmd]
+```
+
+Exports the flow definition as a [Mermaid](https://mermaid.js.org/) flowchart diagram. Useful for documentation, visualization, and reviewing flow logic.
+
+**Options:**
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output` | `-o` | Write diagram to file (default: stdout) |
+| `--format` | | Output format (default: `mermaid`) |
+
+**Example:**
+
+```bash
+flowengine-cli graph intake.rb
+```
+
+Outputs:
+
+```mermaid
+flowchart TD
+  filing_status["What is your filing status?"]
+  filing_status --> income_types
+  income_types["Select all income types that apply:"]
+  income_types -->|"Business in income_types"| business_details
+  income_types --> summary
+  business_details["How many of each business type?"]
+  business_details --> summary
+  summary["Thank you for completing the intake!"]
+```
+
+Save to a file and render with any Mermaid-compatible tool (GitHub, VS Code, mermaid.live):
+
+```bash
+flowengine-cli graph intake.rb -o flow.mmd
+```
+
+---
+
+### `validate` -- Validate Flow Definition
+
+```bash
+flowengine-cli validate <flow_file.rb>
+```
+
+Validates a flow definition file for structural correctness. Checks for:
+
+- **Start step existence** -- is the declared start step defined?
+- **Transition targets** -- do all transitions point to steps that exist?
+- **Reachability** -- are there orphan steps unreachable from the start?
+
+**Example (valid flow):**
+
+```bash
+$ flowengine-cli validate intake.rb
+Flow definition is valid!
+  Start step: filing_status
+  Total steps: 4
+  Steps: filing_status, income_types, business_details, summary
+```
+
+**Example (flow with errors):**
+
+```bash
+$ flowengine-cli validate broken_flow.rb
+Flow definition has errors:
+  - Step :income_types has transition to unknown step :nonexistent
+  - Step :orphan is unreachable from start step :filing_status
+```
+
+---
+
+### `version` -- Print Version
+
+```bash
+$ flowengine-cli version
+flowengine-cli 0.1.0
+flowengine 0.1.0
+```
+
+## Step Types & TTY Rendering
+
+The `Renderer` maps each `FlowEngine::Node` type to the appropriate [TTY::Prompt](https://github.com/piotrmurach/tty-prompt) widget:
+
+| Step Type | DSL | TTY Widget | Returns |
+|-----------|-----|------------|---------|
+| `:single_select` | `type :single_select` | `prompt.select` | `String` |
+| `:multi_select` | `type :multi_select` | `prompt.multi_select` (min: 1) | `Array<String>` |
+| `:number_matrix` | `type :number_matrix` | `prompt.ask` per field (int) | `Hash<String, Integer>` |
+| `:text` | `type :text` | `prompt.ask` | `String` |
+| `:number` | `type :number` | `prompt.ask` (convert: int) | `Integer` |
+| `:boolean` | `type :boolean` | `prompt.yes?` | `true` / `false` |
+| `:display` | `type :display` | Prints text, waits for keypress | `nil` |
+
+Unknown types fall back to `:text` rendering.
+
+## Flow Definition DSL
+
+Flow files are plain Ruby scripts that call `FlowEngine.define`. The full DSL is provided by the `flowengine` core gem:
+
+```ruby
+FlowEngine.define do
+  start :first_step                    # Required: declare entry point
+
+  step :first_step do
+    type :single_select                # Step type (see table above)
+    question "Pick one:"               # Prompt text shown to user
+    options %w[A B C]                  # Choices (for select types)
+    fields %w[X Y Z]                   # Fields (for number_matrix)
+    visible_if not_empty(:some_step)   # Optional: DAG visibility rule
+
+    # Transitions (evaluated top-to-bottom, first match wins)
+    transition to: :step_b, if_rule: equals(:first_step, "A")
+    transition to: :step_c, if_rule: contains(:first_step, "B")
+    transition to: :default_step       # Unconditional fallback
+  end
+end
+```
+
+### Available Rules
+
+Rules are composable AST objects used in `if_rule:` and `visible_if`:
+
+| Rule | DSL Helper | Evaluates |
+|------|-----------|-----------|
+| Contains | `contains(:step, "val")` | `Array(answers[:step]).include?("val")` |
+| Equals | `equals(:step, "val")` | `answers[:step] == "val"` |
+| GreaterThan | `greater_than(:step, 100)` | `answers[:step].to_i > 100` |
+| LessThan | `less_than(:step, 5)` | `answers[:step].to_i < 5` |
+| NotEmpty | `not_empty(:step)` | `answers[:step]` is not nil, "", or [] |
+| All (AND) | `all(rule1, rule2)` | All sub-rules must be true |
+| Any (OR) | `any(rule1, rule2)` | At least one sub-rule must be true |
+
+### Composing Rules
+
+```ruby
+transition to: :special_path,
+           if_rule: all(
+             equals(:filing_status, "Married"),
+             greater_than(:income, 100_000),
+             any(
+               contains(:income_types, "Business"),
+               contains(:income_types, "Investment")
+             )
+           )
+```
+
+## Full Example: Tax Intake Flow
+
+Here is a realistic 17-step tax preparation intake flow demonstrating conditional branching, composite rules, and multiple paths:
+
+```ruby
+# tax_intake.rb
+FlowEngine.define do
+  start :filing_status
+
+  step :filing_status do
+    type :single_select
+    question "What is your filing status for 2025?"
+    options %w[single married_filing_jointly married_filing_separately head_of_household]
+    transition to: :dependents
+  end
+
+  step :dependents do
+    type :number
+    question "How many dependents do you have?"
+    transition to: :income_types
+  end
+
+  step :income_types do
+    type :multi_select
+    question "Select all income types that apply to you in 2025."
+    options %w[W2 1099 Business Investment Rental Retirement]
+    transition to: :business_count, if_rule: contains(:income_types, "Business")
+    transition to: :investment_details, if_rule: contains(:income_types, "Investment")
+    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  step :business_count do
+    type :number
+    question "How many total businesses do you own or are a partner in?"
+    transition to: :complex_business_info, if_rule: greater_than(:business_count, 2)
+    transition to: :business_details
+  end
+
+  step :complex_business_info do
+    type :text
+    question "With more than 2 businesses, please provide your primary EIN and a brief description."
+    transition to: :business_details
+  end
+
+  step :business_details do
+    type :number_matrix
+    question "How many of each business type do you own?"
+    fields %w[RealEstate SCorp CCorp Trust LLC]
+    transition to: :investment_details, if_rule: contains(:income_types, "Investment")
+    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  step :investment_details do
+    type :multi_select
+    question "What types of investments do you hold?"
+    options %w[Stocks Bonds Crypto RealEstate MutualFunds]
+    transition to: :crypto_details, if_rule: contains(:investment_details, "Crypto")
+    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  step :crypto_details do
+    type :text
+    question "Describe your cryptocurrency transactions (exchanges, approximate transaction count)."
+    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  step :rental_details do
+    type :number_matrix
+    question "Provide details about your rental properties."
+    fields %w[Residential Commercial Vacation]
+    transition to: :state_filing
+  end
+
+  step :state_filing do
+    type :multi_select
+    question "Which states do you need to file in?"
+    options %w[California NewYork Texas Florida Illinois Other]
+    transition to: :foreign_accounts
+  end
+
+  step :foreign_accounts do
+    type :single_select
+    question "Do you have any foreign financial accounts?"
+    options %w[yes no]
+    transition to: :foreign_account_details, if_rule: equals(:foreign_accounts, "yes")
+    transition to: :deduction_types
+  end
+
+  step :foreign_account_details do
+    type :number
+    question "How many foreign accounts do you have?"
+    transition to: :deduction_types
+  end
+
+  step :deduction_types do
+    type :multi_select
+    question "Which additional deductions apply to you?"
+    options %w[Medical Charitable Education Mortgage None]
+    transition to: :charitable_amount, if_rule: contains(:deduction_types, "Charitable")
+    transition to: :contact_info
+  end
+
+  step :charitable_amount do
+    type :number
+    question "What is your total estimated charitable contribution amount for 2025?"
+    transition to: :charitable_documentation, if_rule: greater_than(:charitable_amount, 5000)
+    transition to: :contact_info
+  end
+
+  step :charitable_documentation do
+    type :text
+    question "For contributions over $5,000, please list the organizations and amounts."
+    transition to: :contact_info
+  end
+
+  step :contact_info do
+    type :text
+    question "Please provide your contact information (name, email, phone)."
+    transition to: :review
+  end
+
+  step :review do
+    type :text
+    question "Thank you! Please review your information. Type 'confirm' to submit."
+  end
+end
+```
+
+Run it:
+
+```bash
+flowengine-cli run tax_intake.rb -o tax_results.json
+```
+
+Visualize it:
+
+```bash
+flowengine-cli graph tax_intake.rb -o tax_flow.mmd
+```
+
+The Mermaid output renders as:
+
+```mermaid
+flowchart TD
+  filing_status["What is your filing status for 2025?"]
+  filing_status --> dependents
+  dependents["How many dependents do you have?"]
+  dependents --> income_types
+  income_types["Select all income types that apply to you in 2025."]
+  income_types -->|"Business in income_types"| business_count
+  income_types -->|"Investment in income_types"| investment_details
+  income_types -->|"Rental in income_types"| rental_details
+  income_types --> state_filing
+  business_count["How many total businesses do you own or are a part..."]
+  business_count -->|"business_count > 2"| complex_business_info
+  business_count --> business_details
+  complex_business_info["With more than 2 businesses, please provide your p..."]
+  complex_business_info --> business_details
+  business_details["How many of each business type do you own?"]
+  business_details -->|"Investment in income_types"| investment_details
+  business_details -->|"Rental in income_types"| rental_details
+  business_details --> state_filing
+  investment_details["What types of investments do you hold?"]
+  investment_details -->|"Crypto in investment_details"| crypto_details
+  investment_details -->|"Rental in income_types"| rental_details
+  investment_details --> state_filing
+  crypto_details["Describe your cryptocurrency transactions..."]
+  crypto_details -->|"Rental in income_types"| rental_details
+  crypto_details --> state_filing
+  rental_details["Provide details about your rental properties."]
+  rental_details --> state_filing
+  state_filing["Which states do you need to file in?"]
+  state_filing --> foreign_accounts
+  foreign_accounts["Do you have any foreign financial accounts?"]
+  foreign_accounts -->|"foreign_accounts == yes"| foreign_account_details
+  foreign_accounts --> deduction_types
+  foreign_account_details["How many foreign accounts do you have?"]
+  foreign_account_details --> deduction_types
+  deduction_types["Which additional deductions apply to you?"]
+  deduction_types -->|"Charitable in deduction_types"| charitable_amount
+  deduction_types --> contact_info
+  charitable_amount["What is your total estimated charitable contributi..."]
+  charitable_amount -->|"charitable_amount > 5000"| charitable_documentation
+  charitable_amount --> contact_info
+  charitable_documentation["For contributions over $5,000, please list the org..."]
+  charitable_documentation --> contact_info
+  contact_info["Please provide your contact information..."]
+  contact_info --> review
+  review["Thank you! Please review your information."]
+```
+
+## Architecture
+
+```
+                 +-------------------+
+                 |    flowengine     |
+                 |   (core gem)      |
+                 |-------------------|
+                 | DSL + Definition  |
+                 | AST Rules         |
+                 | Evaluator         |
+                 | Engine Runtime    |
+                 | Mermaid Exporter  |
+                 +-------------------+
+                          ^
+                          |
+              +-----------+-----------+
+              |  flowengine-cli       |
+              |-----------------------|
+              | Dry::CLI commands     |
+              | TTY::Prompt renderer  |
+              | Flow file loader      |
+              | JSON output           |
+              +-----------------------+
+```
+
+The core `flowengine` gem has **zero UI dependencies**. It provides the DSL, rule evaluation, and engine runtime. This gem (`flowengine-cli`) is a thin adapter that:
+
+1. **Loads** flow definitions from `.rb` files via `FlowLoader`
+2. **Renders** each step type to the appropriate TTY::Prompt widget via `Renderer`
+3. **Drives** the engine loop until completion
+4. **Outputs** results as structured JSON
+
+## Development
+
+```bash
+git clone https://github.com/kigster/flowengine-cli.git
+cd flowengine-cli
+bin/setup
+bundle exec rspec
+```
+
+Tests use mocked `TTY::Prompt` instances so they run non-interactively. Coverage is enforced at 90% minimum via SimpleCov.
+
+```bash
+bundle exec rspec           # Run tests
+bundle exec rubocop         # Lint
+bundle exec rake            # Both
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/kigster/flowengine-cli).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'timeout'
+require 'yard'
+
+def shell(*args)
+  puts "running: #{args.join(' ')}"
+  system(args.join(' '))
+end
+
+task :clean do
+  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+end
+
+task gem: [:build] do
+  shell('gem install pkg/*')
+end
+
+task permissions: [:clean] do
+  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+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/
+end
+
+
+task build: :permissions
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/flow

@@ -0,0 +1 @@
+flowengine-cli

data/exe/flowengine-cli

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "flowengine/cli"
+
+Dry::CLI.new(FlowEngine::CLI::Commands).call

data/justfile

@@ -0,0 +1,43 @@
+set shell := ["bash", "-c"]
+
+set dotenv-load
+
+# Boot the app
+test:
+    @bundle check ||  bundle install -j 12
+    @bundle exec rspec --format documentation
+
+# Setup Ruby dependencies
+setup-ruby:
+    #!/usr/bin/env bash
+    [[ -d ~/.rbenv ]] || git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+    [[ -d ~/.rbenv/plugins/ruby-build ]] || git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+    cd ~/.rbenv/plugins/ruby-build && git pull && cd - >/dev/null
+    echo -n "Checking if Ruby $(cat .ruby-version | tr -d '\n') is already installed..."
+    rbenv install -s "$(cat .ruby-version | tr -d '\n')" >/dev/null 2>&1 && echo "yes" || echo "it wasn't, but now it is"
+    bundle check || bundle install -j 12
+
+# Setup NodeJS dependencies with Volta
+setup-node:
+    @bash -c "command -v volta > dev/null 2>&1 || brew install volta"
+    @volta install node
+    @volta install yarn
+
+# Setup everything
+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
+
+format:
+    @bundle exec rubocop -a
+    @bundle exec rubocop --auto-gen-config
+
+lint: 
+    @bundle exec rubocop
+
+check-all: lint test
+

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module CLI
+    module Commands
+      class Graph < Dry::CLI::Command
+        desc "Export a flow definition as a Mermaid diagram"
+
+        argument :flow_file, required: true, desc: "Path to flow definition (.rb file)"
+        option :output, aliases: ["-o"], desc: "Output file (default: stdout)"
+        option :format, default: "mermaid", desc: "Output format (mermaid)"
+
+        def call(flow_file:, **options)
+          definition = FlowLoader.load(flow_file)
+
+          mermaid = FlowEngine::Graph::MermaidExporter.new(definition).export
+
+          if options[:output]
+            File.write(options[:output], mermaid)
+            warn "Diagram written to #{options[:output]}"
+          else
+            puts mermaid
+          end
+        rescue FlowEngine::CLI::Error => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "tty-box"
+require "tty-screen"
+
+module FlowEngine
+  module CLI
+    module Commands
+      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"
+
+        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]
+        rescue FlowEngine::CLI::Error => e
+          display_error(e.message)
+          exit 1
+        rescue FlowEngine::Error => e
+          display_error("Engine error: #{e.message}")
+          exit 1
+        end
+
+        private
+
+        def run_flow(flow_file)
+          definition = FlowLoader.load(flow_file)
+          engine = FlowEngine::Engine.new(definition)
+          renderer = Renderer.new
+
+          display_header("FlowEngine Interactive Wizard")
+
+          until engine.finished?
+            display_step_indicator(engine.current_step_id, engine.history.length)
+            engine.answer(renderer.render(engine.current_step))
+          end
+
+          engine
+        end
+
+        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
+
+        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
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module CLI
+    module Commands
+      class ValidateFlow < Dry::CLI::Command
+        desc "Validate a flow definition file"
+
+        argument :flow_file, required: true, desc: "Path to flow definition (.rb file)"
+
+        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 FlowEngine::CLI::Error => e
+          warn "Error: #{e.message}"
+          exit 1
+        rescue FlowEngine::Error => e
+          warn "Definition error: #{e.message}"
+          exit 1
+        end
+
+        private
+
+        def print_success(definition)
+          puts "Flow definition is valid!"
+          puts "  Start step: #{definition.start_step_id}"
+          puts "  Total steps: #{definition.step_ids.length}"
+          puts "  Steps: #{definition.step_ids.join(", ")}"
+        end
+
+        def print_errors(errors)
+          warn "Flow definition has errors:"
+          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} has transition 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 do |orphan|
+            errors << "Step :#{orphan} is unreachable from start step :#{definition.start_step_id}"
+          end
+        end
+
+        def find_reachable_steps(definition)
+          visited = Set.new
+          queue = [definition.start_step_id]
+          known_ids = definition.step_ids
+
+          until queue.empty?
+            current = queue.shift
+            next if visited.include?(current)
+
+            visited << current
+            next unless known_ids.include?(current)
+
+            enqueue_transitions(definition.step(current), known_ids, queue)
+          end
+
+          visited.to_a
+        end
+
+        def enqueue_transitions(step, known_ids, queue)
+          step.transitions.each do |t|
+            queue << t.target if known_ids.include?(t.target)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module CLI
+    module Commands
+      class Version < Dry::CLI::Command
+        desc "Print version information"
+
+        def call(**)
+          puts "flowengine-cli #{FlowEngine::CLI::VERSION}"
+          puts "flowengine #{FlowEngine::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/cli/commands.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "commands/run"
+require_relative "commands/graph"
+require_relative "commands/validate_flow"
+require_relative "commands/version"
+
+module FlowEngine
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      register "run", Run
+      register "graph", Graph
+      register "validate", ValidateFlow
+      register "version", Version
+    end
+  end
+end

data/lib/flowengine/cli/flow_loader.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module CLI
+    class FlowLoader
+      def self.load(path)
+        new(path).load
+      end
+
+      def initialize(path)
+        @path = File.expand_path(path)
+        validate_path!
+      end
+
+      def load
+        content = File.read(@path)
+        # Evaluate in a clean binding that has FlowEngine available
+        # rubocop:disable Security/Eval
+        eval(content, TOPLEVEL_BINDING.dup, @path, 1)
+        # rubocop:enable Security/Eval
+      rescue SyntaxError => e
+        raise FlowEngine::CLI::Error, "Syntax error in #{@path}: #{e.message}"
+      end
+
+      private
+
+      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")
+      end
+    end
+  end
+end

data/lib/flowengine/cli/renderer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module FlowEngine
+  module CLI
+    class Renderer
+      attr_reader :prompt
+
+      def initialize(prompt: TTY::Prompt.new)
+        @prompt = prompt
+      end
+
+      def render(node)
+        method_name = :"render_#{node.type}"
+
+        if respond_to?(method_name, true)
+          send(method_name, node)
+        else
+          render_text(node)
+        end
+      end
+
+      private
+
+      def render_multi_select(node)
+        prompt.multi_select(node.question, node.options, min: 1)
+      end
+
+      def render_single_select(node)
+        prompt.select(node.question, node.options)
+      end
+
+      def render_number_matrix(node)
+        puts "\n#{node.question}\n\n"
+        result = {}
+        node.fields.each do |field|
+          result[field] = prompt.ask("  #{field}:", convert: :int, default: 0)
+        end
+        result
+      end
+
+      def render_text(node)
+        prompt.ask(node.question)
+      end
+
+      def render_number(node)
+        prompt.ask(node.question, convert: :int)
+      end
+
+      def render_boolean(node) # rubocop:disable Naming/PredicateMethod
+        prompt.yes?(node.question)
+      end
+
+      def render_display(node)
+        puts "\n#{node.question}\n"
+        prompt.keypress("Press any key to continue...")
+        nil
+      end
+    end
+  end
+end

data/lib/flowengine/cli/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module CLI
+    VERSION = "0.1.0"
+  end
+end

data/lib/flowengine/cli.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "flowengine"
+require_relative "cli/version"
+require_relative "cli/flow_loader"
+require_relative "cli/renderer"
+require_relative "cli/commands"
+
+module FlowEngine
+  module CLI
+    class Error < StandardError; end
+  end
+end

data/sig/flowengine/cli.rbs

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

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: flowengine-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.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: flowengine
+  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: 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-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'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a TTY-based CLI to run FlowEngine flow definitions interactively,
+  export Mermaid diagrams, and validate flow files.
+email:
+- kigster@gmail.com
+executables:
+- flow
+- flowengine-cli
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".rubocop_todo.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/flow
+- exe/flowengine-cli
+- justfile
+- lib/flowengine/cli.rb
+- lib/flowengine/cli/commands.rb
+- lib/flowengine/cli/commands/graph.rb
+- lib/flowengine/cli/commands/run.rb
+- lib/flowengine/cli/commands/validate_flow.rb
+- lib/flowengine/cli/commands/version.rb
+- lib/flowengine/cli/flow_loader.rb
+- lib/flowengine/cli/renderer.rb
+- lib/flowengine/cli/version.rb
+- sig/flowengine/cli.rbs
+homepage: https://github.com/kigster/flowengine-cli
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/flowengine-cli
+  source_code_uri: https://github.com/kigster/flowengine-cli
+  changelog_uri: https://github.com/kigster/flowengine-cli/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.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Terminal-based interactive wizard runner for FlowEngine flows
+test_files: []