flowengine-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ff826ab26eb55ed836e66300baf943197a13f17b4d44886ab784a303f919978
+  data.tar.gz: dbd3b01d8eff30c0ed0b7b9054ccc5769161afb350f14cdce34bd6b62a6dbf70
+SHA512:
+  metadata.gz: 91d37ce06fcaee18b93c05e5a79bafdd891c9906238bc5ad542f1866c3d9abee4263706d70b65c948b76b1fdb999bb74be67a4fdfc5bcdf2071146163960536d
+  data.tar.gz: 6b6f9f96accc3f9be1dd01d7b35d8fb6e7a634016d5eb5dccf0639ebc0c2dd39d2136c21dcb719e11433faeae04decedbc0261a9e51dc96b76ed25515b935229

data/.claude/branch-name.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# ANSI color codes
+BOLD_YELLOW='\033[1;33m'
+BOLD_RED='\033[1;31m'
+RESET='\033[0m'
+
+while true; do
+	if [[ -z "$*" ]]; then
+		# Prompt user (to STDERR)
+		echo -n "Please name the branch for your changes: " >&2
+
+		# Print bold yellow escape sequence
+		echo -ne "${BOLD_YELLOW}" >&2
+
+		# Read user input
+		read branch_input
+	else
+		branch_input="$*"
+	fi
+
+	# Reset color
+	echo -ne "${RESET}" >&2
+
+	# Transform the input:
+	# 1. Replace non-alphanumeric (except / and space) with dash
+	# 2. Replace sequences of multiple dashes with single dash
+	# 3. Convert to lowercase
+	branch_name="$(echo "${branch_input}" |
+		sed -E 's/[^a-zA-Z0-9/-]/-/g' |
+		sed -E 's/-+/-/g; ' |
+		tr '[:upper:]' '[:lower:]')"
+
+	# Prepend $USER/ if not already present
+	if [[ ! "$branch_name" =~ ^${USER}/ ]]; then
+		branch_name="${USER}/${branch_name}"
+	fi
+
+	# Check length
+	if [ ${#branch_name} -gt 50 ]; then
+		echo -e "${BOLD_RED}Error: Branch name is too long (${#branch_name} characters, max 50)${RESET}" >&2
+		echo >&2
+		continue
+	fi
+
+	# Output the branch name to STDOUT
+	echo "${branch_name}"
+	break
+done

data/.claude/commands/create-pr.md

@@ -0,0 +1,93 @@
+---
+
+description: "Create a pull request from current branch or staged changes"
+allowed-tools:
+
+- Bash(./.claude/branch-name.sh)
+- Bash(just check-all:\*)
+- Bash(git \*)
+- Bash(gh \*)
+
+---
+
+# Create One or More Pull Request from the Currently Modified or Staged Files
+
+IMPORTANT: NON-INTERACTIVITY. This command should complete nearly always without human interaction. Only if you are really confused or lacking a major permission should you pause and ask question. Assume that the human is away from the keyboard while you are submitting their changes as PRs.
+
+## Command's Purpose
+
+The purpose of this command is to take all locally modified files (staged or not), split them into unrelated, or related but stackable commits and PRs, and do it non-interactively, and do it in such a away that both locally and on Github CI (if there is one) each PR passes, does not have merge conflicts, and should be ready to be reviewed and merged.
+
+## Steps to Accomplish
+
+1. First, feel free to `git add . ` so that all the modified files are staged. This command is deliberately mean to commit ALL modified files for simplicity, otherwise it's difficult to identify what should or should not be committed.
+2. Second, if the repo supports command `just format` or `make format` or `rubocop -a` (or other safe linter fix commandss) — go ahead and run them now. If there are locally modified files, `git add` them.
+3. If we are NOT on the main branch, then do a diff between the current branch and the main (excluding the staged files) to understand what the context of the current branch is. 
+4. Next you are going to review all the staged files and break them up by "context": i.e. that means they need to be committed and pushed to a PR together.  This will also help you identify which files should be committed into the current branch (i.e. they all relate to the changes on this branch, or the branch name). If there are several unrelated changes in this set of staged files, OR multiple related changes, but there are a lot of changes (the diff is > 500 lines) you will need to break up this PR into multiple PRs.
+
+Multiple PRs can either be on branches that are created off main (those changes should have nothing to do with the current branch), OR they can be committed and pushed as multiple PRs that are stacked on each other.
+
+For every commit and branch that you push you must ensure that local tests are passing and if not either fix them (if that's easy) or refuse to push a PR until you pairing with the developer resolve all test issues. 
+
+Tests are typically invoked as:
+
+```
+just test # if there is a justfile at the root
+make test # if there is a Makefile at the root
+bundle exec rspec --format documentation # if this is a ruby repo, meaning there is a Gemfile and Gemfile.lock at the root level and spec folder
+npm run test # if there is package.json and a test command
+# for other types of repos identify the most common ways to run tests, and do run them before committing any code.
+```
+
+## Branch Names
+
+We provided a convenient shell script in the .claude directory, called `./.claude/branch-name.sh`
+
+To generate a new branch name, identify from three to six key words describing this change and  then run from the project root:
+
+```bash
+$ .claude/branch-name.sh add copilot LLM bubble for admins # this script will output the following
+kig/add-copilot-llm-bubble-for-admins
+```
+
+If you run this script, capture it's STDOUT and you'll get the branch name.
+
+It prefixes the current user `$USER` and a slash, and then dash-joins all the words you specified.
+
+If you need information on how to split one large PR into smaller ones, the following URLs might be helpful:
+
+- https://www.davepacheco.net/blog/2025/stacked-prs-on-github/
+- https://itsnotbugitsfeature.com/2019/10/22/splitting-a-big-pull-request-into-smaller-review-able-ones
+- https://newsletter.pragmaticengineer.com/p/stacked-diffs
+
+## Committing Changes and Creating the PR
+
+Once we are on the appropriate branch, and either there are only changes staged for commit or NO changes at all (so we'll be creating the PR from the branch).
+
+## Rebase from main?
+
+Compare the local main with remote main, and if they diverged, you'll want to stash all the changes, switch to main, do git pull, then restore the branch, and before you pop the stash, run `git rebase main`. Resolve any conflicts that you are able to do on your own, otherwise this is one case where you can engage interactively and ask the developer for help. Once the current branch is rebased, you `git stash pop`. This may also result in conflicts. The same thing: attempt to resolve them and commit the rebase, or engage with the developer.
+
+### Committing Currently Staged Changes
+
+At this point, you should either a clean branch with all changes committed, or some changes staged for commit.
+
+If there are changes staged for commit, you must perform `git diff --cached`, and summarize those changes in the markdown format in a temporary file we'll call <tempfile> (preferably under /tmp folder), and create a short title for the commit.
+
+Then we commit with `git commit -m "<title>" -F "<tempfile>"`, and push the changes `git push -u origin`.
+
+### Creating the PR
+
+This is the final step. You are to use command `gh` (which stands for `github`).
+
+In order to create a PR we must NOT be on the `main` branch, we must have all changes pushed to the origin and we must have no locally untracked or modified files.
+
+The next step is describing the PR.
+
+You are going to perform the diff of the current branch with the remote `main` branch using `git diff origin/main...HEAD`, and analyze it. You will create a markdown file that we'll refer to <pr-description> preferably in the `/tmp` folder, that describes the changes of this PR precisely, professionally, without any emojis. It should have the top header title that we'll refer to <pr-title>, (with a single '#' in markdown) that will also be the name of the PR. It should have the sections such as Summary (a short abstract-type description, no more than a few paragraphs) Description (if necessary, a more detailed description), Motivation, Testing, Backwards Compatibility, Scalability & Performance Impact, and Code Quality Analysis.
+
+Once completed analysis and summarizing of this change, you will invoke the command `gh pr create -a @me -B main -F "<pr-description>" -t "<pr-title>"`.
+
+If the command responds with an error such as Github Token authorization is insufficient, you are to save the PR description in the file at the root of the project called `PR.md` and report this to the user. Also print the URL required to create the PR on the web by clicking on the URL.
+
+If you were able to create the PR with the `gh pr create` command, then open the web page to it anyway. Get the PR ID with `gh pr list | grep "<pr-title>" | awk '{print $1}'`

data/.claude/commands/stash-unstaged.md

@@ -0,0 +1,21 @@
+---
+
+description: "Stash unstaged/untracked files while preserving staged changes"
+allowed-tools:
+
+- Bash(git \*)
+
+---
+
+# Stash Unstaged Changes
+
+This command stashes unstaged and untracked files while preserving any files already staged for commit.
+
+Check if there are any files staged for commit (i.e. git added) with `git diff --cached`
+
+- If there are none, simply run `git stash push --include-untracked`
+- If there are unstaged changes in the workspace in addition to staged, you are to perform the following series of commands:
+  1. `git commit -m 'WIP: staged changes' --no-verify` — commit the staged changes temporarily
+  1. `git stash push --include-untracked` — to stash the remaining unstaged changes
+  1. `git reset --soft HEAD^` — to undo the temporary commit
+  1. `git add .` — to stage the previously staged for commit files

data/.claude/commands/unstash-unstaged.md

@@ -0,0 +1,15 @@
+---
+
+description: "Restore previously stashed unstaged changes"
+allowed-tools:
+
+- Bash(git \*)
+
+---
+
+# Unstash Unstaged Changes
+
+This command brings back the changes made by the "stash-unstaged" command.
+
+Ensure that the current workspace is clean (no staged or unstaged files) and if there are any — ask if the user still wants to proceed.
+If the user confirms, run `git stash apply` command to bring back previously stashed changes.

data/.claude/settings.json

@@ -0,0 +1,72 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit",
+      "Bash(*)",
+      "Bash(chmod:*)",
+      "Skill(create-pr)",
+      "WebFetch(domain:docs.tabler.io)",
+      "WebFetch(domain:smartdatalake.ch)",
+      "WebSearch",
+      "WebFetch(*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:www.vcpr.cz)",
+      "WebFetch(domain:renju.net)",
+      "WebFetch(domain:en.wikipedia.org)"
+    ]
+  },
+  "enabledPlugins": {
+    "activerecord@claude-ruby-marketplace": true,
+    "build@motlin-claude-code-plugins": true,
+    "chrome-devtools-mcp@chrome-devtools-plugins": true,
+    "ci-cd@devops-skills": true,
+    "example-skills@anthropic-agent-skills": false,
+    "feature-dev@claude-code-plugins": true,
+    "frontend-design@claude-code-plugins": true,
+    "git@motlin-claude-code-plugins": true,
+    "iac-terraform@devops-skills": true,
+    "justfile@motlin-claude-code-plugins": true,
+    "pr-review-toolkit@claude-code-plugins": true,
+    "rspec@claude-ruby-marketplace": true,
+    "ruby-lsp@ruby-skills": true,
+    "ruby-skills@ruby-skills": true,
+    "security-guidance@claude-code-plugins": true,
+    "superpowers-developing-for-claude-code@superpowers-marketplace": true,
+    "superpowers@superpowers-marketplace": false
+  },
+  "extraKnownMarketplaces": {
+    "ruby-skills": {
+      "source": {
+        "source": "github",
+        "repo": "st0012/ruby-skills"
+      }
+    },
+    "claude-ruby-marketplace": {
+      "source": {
+        "source": "github",
+        "repo": "hoblin/claude-ruby-marketplace"
+      }
+    },
+    "devops-skills": {
+      "source": {
+        "source": "github",
+        "repo": "ahmedasmar/devops-claude-skills"
+      }
+    },
+    "motlin-claude-code-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "motlin/claude-code-plugins"
+      }
+    },
+    "chrome-devtools-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "ChromeDevTools/chrome-devtools-mcp"
+      }
+    }
+  },
+  "effortLevel": "high",
+  "skipDangerousModePermissionPrompt": true
+}

data/.rubocop_todo.yml

@@ -0,0 +1,17 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-03-17 03:19:43 UTC using RuboCop version 1.85.1.
+# 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.
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 20
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 9

data/.ruby-version

@@ -0,0 +1 @@
+4.0.1

data/CHANGELOG.md

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

data/CLAUDE.md

@@ -0,0 +1,153 @@
+# FlowEngine Rails
+
+## What This Gem Does
+
+`flowengine-rails` is a Rails Engine (v0.1.0) that wraps the `flowengine` core gem with ActiveRecord persistence, a Hotwire-based web wizard UI, an admin CRUD interface, and an iframe-embeddable widget. It lets non-technical users define multi-step form flows via a Ruby DSL, store them in the database, and serve them to end users as interactive step-by-step wizards.
+
+The target application is **Qualified.at** -- a lead qualification service where flows are embedded in external client sites via iframes.
+
+## Dependency on `flowengine` Core Gem
+
+The core gem (`flowengine`, published on RubyGems as v0.4.0, source at `github.com/kigster/flowengine`) provides:
+
+- **DSL** for defining flows: `FlowEngine.define { ... }` with steps, transitions, rules
+- **Engine** (state machine): `FlowEngine::Engine` drives step traversal, answers, history
+- **Node** objects representing individual steps with types (`:text`, `:boolean`, `:number`, `:single_select`, `:multi_select`, `:number_matrix`, `:display`)
+- **Graph/MermaidExporter** for diagram visualization
+- **Rules/Evaluator** for conditional transitions (`if_rule:`, `contains()`, etc.)
+- **Validation** for DSL correctness
+
+This gem calls into `flowengine` via:
+- `FlowEngine.load_dsl(dsl_text)` -- parses DSL string into a Definition
+- `FlowEngine::Engine.new(definition)` / `FlowEngine::Engine.from_state(definition, state)` -- creates/restores engine
+- `engine.answer(value)`, `engine.to_state`, `engine.finished?` -- drives flow
+- `definition.step_ids`, `definition.step(id)` -- introspects steps
+- `FlowEngine::Graph::MermaidExporter` -- generates Mermaid diagrams
+
+**Local development**: `Gemfile` uses `path: "../flowengine"` (sibling directory). **CI/branches**: changed to `github: "kigster/flowengine"`. The gemspec declares `spec.add_dependency "flowengine", "~> 0.1"`.
+
+## Repository Layout
+
+```
+flowengine-rails.gemspec        # Gem metadata, deps: flowengine ~> 0.1, rails >= 8.0.1, stimulus-rails, turbo-rails
+Gemfile                         # Dev deps: rspec-rails, rspec-its, rubocop, capybara, simplecov, sqlite3
+Rakefile                        # Default task: spec + rubocop
+
+lib/
+  flowengine/rails.rb           # Entry point, Configuration singleton, Error class
+  flowengine/rails/version.rb   # VERSION = "0.1.0"
+  flowengine/rails/configuration.rb  # embed_allowed_origins, layouts, cache, callbacks, admin auth
+  flowengine/rails/dsl_loader.rb     # Thread-safe in-memory cache around FlowEngine.load_dsl
+  flowengine/rails/engine.rb         # Rails::Engine with asset paths, importmap, generator config
+  generators/
+    flow_engine/install/        # rails g flow_engine:install -- migrations, initializer, route mount
+    flow_engine/flow/           # rails g flow_engine:flow NAME -- definition file + seed rake task
+
+app/
+  models/flow_engine/
+    application_record.rb       # Base AR class
+    flow_definition.rb          # name, version, dsl (text), active (boolean). Validates DSL parses.
+                                # Auto-increments version on create. activate!/deactivate! toggles.
+                                # readonly? when sessions exist. Generates mermaid diagrams.
+    flow_session.rb             # belongs_to definition. Tracks current_step_id, answers (JSON),
+                                # history (JSON), status (in_progress/completed/abandoned).
+                                # advance!(answer) drives the engine. fire_completion_callback on complete.
+  controllers/flow_engine/
+    application_controller.rb   # Embed mode detection (?embed=true), CORS headers, layout switching
+    sessions_controller.rb      # new, create, show, update, completed, abandon
+                                # Parses answer by step type (multi_select->array, number->int, etc.)
+    admin/definitions_controller.rb  # Full CRUD + activate/deactivate/mermaid. Admin auth via config.
+  helpers/flow_engine/
+    sessions_helper.rb          # render_step(node, form) dispatches to type-specific partials
+  views/
+    flow_engine/sessions/       # new, show, completed templates
+    flow_engine/sessions/steps/ # Partials: _boolean, _text, _number, _single_select,
+                                #   _multi_select, _number_matrix, _display, _unknown
+    flow_engine/admin/definitions/  # index, show, new, edit, _form, mermaid
+    layouts/flow_engine/        # application.html.erb (standalone), embed.html.erb (iframe)
+  assets/
+    javascripts/flow_engine/    # embed.js (iframe resizer), progress_controller.js, step_controller.js
+    stylesheets/flow_engine/    # application.css (full standalone stylesheet)
+
+config/routes.rb                # sessions (new/create/show/update + completed/abandon)
+                                # admin/definitions (CRUD + activate/deactivate/mermaid)
+                                # root -> sessions#new
+
+db/migrate/
+  01_create_flow_engine_definitions.rb  # name, version, dsl, active. Unique index on [name, version].
+  02_create_flow_engine_sessions.rb     # definition_id (FK), current_step_id, answers/history/metadata (JSON), status
+
+spec/
+  spec_helper.rb                # SQLite in-memory, schema created inline, SIMPLE_DSL fixture
+  dummy/                        # Minimal Rails 8 app (SQLite :memory:, engine mounted at /flow_engine)
+  controllers/                  # Request specs for sessions + admin/definitions
+  models/                       # Unit specs for FlowDefinition, FlowSession
+  lib/                          # Specs for Configuration, DslLoader
+  routing/                      # Route specs
+
+.github/workflows/
+  main.yml                      # Ruby 3.4.4, bundle exec rake (spec + rubocop)
+  rspec.yml                     # Ruby 4.0, checks out kigster/flowengine alongside, bundle exec rspec
+  rubocop.yml                   # Ruby 4.0, bundle exec rubocop
+```
+
+## Database Schema
+
+**flow_engine_definitions**: `name` (string), `version` (integer, auto-incremented per name), `dsl` (text, Ruby DSL source), `active` (boolean). Unique index on `[name, version]`.
+
+**flow_engine_sessions**: `definition_id` (FK), `current_step_id` (string), `answers` (JSON), `history` (JSON, array of visited step IDs), `status` (string: in_progress/completed/abandoned), `metadata` (JSON).
+
+## Configuration
+
+```ruby
+FlowEngine::Rails.configure do |config|
+  config.embed_allowed_origins = ["https://example.com"]  # CORS for iframe embed
+  config.default_layout = "flow_engine/application"        # Standalone layout
+  config.embed_layout = "flow_engine/embed"                # Iframe layout
+  config.cache_definitions = true                          # In-memory DSL parse cache
+  config.on_session_complete = ->(session) { ... }         # Completion callback
+  config.admin_authentication_method = :authenticate_admin! # Admin before_action
+end
+```
+
+## Step Types and Answer Parsing
+
+| Step type       | View partial       | Answer param          | Parsed as            |
+|-----------------|--------------------|-----------------------|----------------------|
+| `:text`         | `_text`            | `params[:answer]`     | String               |
+| `:number`       | `_number`          | `params[:answer]`     | Integer (`.to_i`)    |
+| `:boolean`      | `_boolean`         | `params[:answer]`     | Boolean (`== "true"`)|
+| `:single_select`| `_single_select`   | `params[:answer]`     | String               |
+| `:multi_select` | `_multi_select`    | `params[:answer_values]` | Array             |
+| `:number_matrix`| `_number_matrix`   | `params[:answer_fields]` | Hash (string->int)|
+| `:display`      | `_display`         | (none, info-only)     | N/A                  |
+
+## Running Tests and Linting
+
+```bash
+bundle exec rspec          # Tests (SQLite in-memory, no external DB needed)
+bundle exec rubocop        # Lint
+bundle exec rake           # Both (default task)
+```
+
+## CI Notes
+
+- **Gemfile.lock must include `x86_64-linux` platform** (`bundle lock --add-platform x86_64-linux`)
+- The `rspec.yml` workflow checks out `kigster/flowengine` as a sibling directory for the path dependency
+- The `main.yml` workflow runs on Ruby 3.4.4; `rspec.yml` and `rubocop.yml` run on Ruby 4.0
+- Required Ruby version: `>= 4.0.1` (gemspec)
+
+## RuboCop Configuration
+
+- Target Ruby 4.0, double quotes enforced, frozen string literal required
+- Line length max 120, method length max 20
+- `spec/dummy/` excluded from cops
+- `inherit_from: .rubocop_todo.yml`
+
+## Key Architectural Patterns
+
+- **Isolated namespace**: all code under `FlowEngine` module, engine uses `isolate_namespace FlowEngine`
+- **Immutable definitions**: once a `FlowDefinition` has sessions, it becomes `readonly?`; users must create a new version
+- **State reconstruction**: `FlowSession#engine` rebuilds `FlowEngine::Engine` from persisted state on every request (stateless controller pattern)
+- **Embed mode**: `?embed=true` query param switches layout and enables CORS headers
+- **Thread-safe caching**: `DslLoader` uses `Mutex` for DSL parse cache

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.