flowengine-rails 0.1.0

data/db/migrate/01_create_flow_engine_definitions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateFlowEngineDefinitions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :flow_engine_definitions do |t|
+      t.string :name, null: false
+      t.integer :version, null: false, default: 1
+      t.text :dsl, null: false
+      t.boolean :active, null: false, default: false
+
+      t.timestamps
+    end
+
+    add_index :flow_engine_definitions, %i[name version], unique: true
+    add_index :flow_engine_definitions, :name, unique: true, where: "active = 1",
+                                               name: "index_flow_engine_definitions_on_name_active"
+  end
+end

data/db/migrate/02_create_flow_engine_sessions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateFlowEngineSessions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :flow_engine_sessions do |t|
+      t.references :definition, null: false, foreign_key: { to_table: :flow_engine_definitions }
+      t.string :current_step_id
+      t.json :answers, default: {}
+      t.json :history, default: []
+      t.string :status, null: false, default: "in_progress"
+      t.json :metadata, default: {}
+
+      t.timestamps
+    end
+
+    add_index :flow_engine_sessions, :status
+  end
+end

data/exe/flowengine-rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "flowengine/rails"

data/justfile

@@ -0,0 +1,49 @@
+set shell := ["bash", "-c"]
+
+set dotenv-load
+
+[no-exit-message]
+recipes:
+    @just --choose
+
+test:
+    @bundle exec rspec
+    @bundle exec rubocop
+
+# 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: setup-ruby
+
+cli DATA SCHEMA *ARGS:
+    #!/usr/bin/env bash
+    cd .. && ./cli validate-json -f {{DATA}} -s {{SCHEMA}}
+
+format:
+    @bundle exec rubocop -a
+    @bundle exec rubocop --auto-gen-config
+
+lint: 
+    @bundle exec rubocop
+
+# Generates library documentation into ./doc folder and opens the browser
+doc:
+    @bundle exec rake doc
+    @open ./doc/index.html
+
+clean:
+    @rm -rf pkg
+    @rm -rf coverage
+
+release:
+    @bundle exec rake release
+
+check-all: lint test
+

data/lefthook.yml

@@ -0,0 +1,16 @@
+pre-commit:
+  parallel: true
+  jobs:
+    - name: format
+      glob: "*.{js,ts,tsx}"
+      run: npx biome format --write {staged_files}
+      stage_fixed: true
+
+    - name: rubocop
+      glob: "*.{rb,rake}"
+      run: bundle exec rubocop -a --format progress {staged_files}
+      staged_fixed: true
+
+    - name: rspecs
+      glob: "spec/**/*_spec.rb"
+      run: bundle exec rspec --format progress

data/lib/flowengine/rails/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module Rails
+    class Configuration
+      attr_accessor :embed_allowed_origins,
+                    :default_layout,
+                    :embed_layout,
+                    :cache_definitions,
+                    :on_session_complete,
+                    :admin_authentication_method
+
+      def initialize
+        @embed_allowed_origins = []
+        @default_layout = "flow_engine/application"
+        @embed_layout = "flow_engine/embed"
+        @cache_definitions = true
+        @on_session_complete = nil
+        @admin_authentication_method = nil
+      end
+    end
+  end
+end

data/lib/flowengine/rails/dsl_loader.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module Rails
+    class DslLoader
+      class << self
+        def load(dsl_text, cache_key: nil)
+          return FlowEngine.load_dsl(dsl_text) unless cache_key && FlowEngine::Rails.configuration.cache_definitions
+
+          cache_fetch(cache_key) { FlowEngine.load_dsl(dsl_text) }
+        end
+
+        def clear_cache!
+          mutex.synchronize { cache.clear }
+        end
+
+        private
+
+        def cache_fetch(key)
+          mutex.synchronize do
+            cache[key] ||= yield
+          end
+        end
+
+        def cache
+          @cache ||= {}
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/rails/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace FlowEngine
+
+      initializer "flow_engine.assets" do |app|
+        app.config.assets.paths << root.join("app", "assets", "stylesheets") if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app", "assets", "javascripts") if app.config.respond_to?(:assets)
+      end
+
+      initializer "flow_engine.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap) && root.join("config",
+                                                           "importmap.rb").exist?
+          app.config.importmap.paths << root.join("config", "importmap.rb")
+        end
+      end
+
+      config.generators do |g|
+        g.test_framework :rspec
+        g.fixture_replacement :factory_bot, dir: "spec/factories"
+      end
+    end
+  end
+end

data/lib/flowengine/rails/version.rb

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

data/lib/flowengine/rails.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "flowengine"
+require_relative "rails/version"
+require_relative "rails/configuration"
+require_relative "rails/dsl_loader"
+require_relative "rails/engine"
+
+module FlowEngine
+  module Rails
+    class Error < StandardError; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/generators/flow_engine/flow/flow_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module Generators
+    class FlowGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a flow definition file and seed task"
+
+      def create_flow_definition
+        template "flow_definition.rb.tt", "db/flow_definitions/#{file_name}.rb"
+      end
+
+      def create_seed_task
+        template "seed_task.rake.tt", "lib/tasks/flow_engine_#{file_name}.rake"
+      end
+
+      def show_next_steps
+        say ""
+        say "Flow definition created!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Edit db/flow_definitions/#{file_name}.rb"
+        say "  2. Seed it:  rails flow_engine:seed:#{file_name}"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/flow_engine/flow/templates/flow_definition.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Flow definition: <%= class_name %>
+# Edit this file then seed it with: rails flow_engine:seed:<%= file_name %>
+
+<%= class_name.upcase %>_DSL = <<~RUBY
+  FlowEngine.define do
+    start :welcome
+
+    step :welcome do
+      type :display
+      question "Welcome to the <%= class_name.titleize %> flow!"
+      transition to: :first_question
+    end
+
+    step :first_question do
+      type :text
+      question "What is your name?"
+      transition to: :done
+    end
+
+    step :done do
+      type :display
+      question "Thank you for completing the flow!"
+    end
+  end
+RUBY

data/lib/generators/flow_engine/flow/templates/seed_task.rake.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+namespace :flow_engine do
+  namespace :seed do
+    desc "Seed the <%= class_name %> flow definition"
+    task <%= file_name %>: :environment do
+      require Rails.root.join("db/flow_definitions/<%= file_name %>")
+
+      dsl_text = <%= class_name.upcase %>_DSL
+
+      definition = FlowEngine::Definition.find_or_initialize_by(
+        name: "<%= file_name %>",
+        version: 1
+      )
+      definition.dsl = dsl_text
+      definition.save!
+      definition.activate!
+
+      puts "Seeded and activated: #{definition.name} v#{definition.version}"
+    end
+  end
+end

data/lib/generators/flow_engine/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install FlowEngine: copy migrations, create initializer, add mount route"
+
+      def copy_migrations
+        rake "flow_engine:install:migrations"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/flow_engine.rb"
+      end
+
+      def add_route
+        route 'mount FlowEngine::Rails::Engine => "/flow_engine"'
+      end
+
+      def show_post_install
+        say ""
+        say "FlowEngine installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run migrations:  rails db:migrate"
+        say "  2. Edit config/initializers/flow_engine.rb"
+        say "  3. Create a flow:   rails generate flow_engine:flow my_intake"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/flow_engine/install/templates/initializer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+FlowEngine::Rails.configure do |config|
+  # Origins allowed to embed the flow widget via iframe.
+  # Use ["*"] to allow all origins, or specify domains:
+  # config.embed_allowed_origins = ["https://example.com"]
+  config.embed_allowed_origins = []
+
+  # Layout used for regular (non-embedded) flow sessions
+  # config.default_layout = "flow_engine/application"
+
+  # Layout used for embedded (iframe) flow sessions
+  # config.embed_layout = "flow_engine/embed"
+
+  # Cache parsed DSL definitions in memory (recommended for production)
+  config.cache_definitions = Rails.env.production?
+
+  # Callback fired when a session is completed.
+  # Receives the completed FlowEngine::Session instance.
+  # config.on_session_complete = ->(session) { MyNotifier.flow_completed(session) }
+
+  # Method name to call on ApplicationController for admin authentication.
+  # Set to nil to disable (open admin). Example: :authenticate_admin!
+  # config.admin_authentication_method = :authenticate_admin!
+end

data/sig/flowengine/rails.rbs

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

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: flowengine-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  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: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: FlowEngine::Rails provides ActiveRecord persistence, Hotwire-based web
+  wizard UI, admin CRUD for flow definitions, and an iframe-embeddable widget. Built
+  on the flowengine core gem.
+email:
+- kigster@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/branch-name.sh"
+- ".claude/commands/create-pr.md"
+- ".claude/commands/stash-unstaged.md"
+- ".claude/commands/unstash-unstaged.md"
+- ".claude/settings.json"
+- ".rubocop_todo.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/flow_engine/embed.js
+- app/assets/javascripts/flow_engine/progress_controller.js
+- app/assets/javascripts/flow_engine/step_controller.js
+- app/assets/stylesheets/flow_engine/application.css
+- app/controllers/flow_engine/admin/definitions_controller.rb
+- app/controllers/flow_engine/application_controller.rb
+- app/controllers/flow_engine/sessions_controller.rb
+- app/helpers/flow_engine/sessions_helper.rb
+- app/models/flow_engine/application_record.rb
+- app/models/flow_engine/flow_definition.rb
+- app/models/flow_engine/flow_session.rb
+- app/views/flow_engine/admin/definitions/_form.html.erb
+- app/views/flow_engine/admin/definitions/edit.html.erb
+- app/views/flow_engine/admin/definitions/index.html.erb
+- app/views/flow_engine/admin/definitions/mermaid.html.erb
+- app/views/flow_engine/admin/definitions/new.html.erb
+- app/views/flow_engine/admin/definitions/show.html.erb
+- app/views/flow_engine/sessions/completed.html.erb
+- app/views/flow_engine/sessions/new.html.erb
+- app/views/flow_engine/sessions/show.html.erb
+- app/views/flow_engine/sessions/steps/_boolean.html.erb
+- app/views/flow_engine/sessions/steps/_display.html.erb
+- app/views/flow_engine/sessions/steps/_multi_select.html.erb
+- app/views/flow_engine/sessions/steps/_number.html.erb
+- app/views/flow_engine/sessions/steps/_number_matrix.html.erb
+- app/views/flow_engine/sessions/steps/_single_select.html.erb
+- app/views/flow_engine/sessions/steps/_text.html.erb
+- app/views/flow_engine/sessions/steps/_unknown.html.erb
+- app/views/layouts/flow_engine/application.html.erb
+- app/views/layouts/flow_engine/embed.html.erb
+- config/routes.rb
+- db/migrate/01_create_flow_engine_definitions.rb
+- db/migrate/02_create_flow_engine_sessions.rb
+- exe/flowengine-rails
+- justfile
+- lefthook.yml
+- lib/flowengine/rails.rb
+- lib/flowengine/rails/configuration.rb
+- lib/flowengine/rails/dsl_loader.rb
+- lib/flowengine/rails/engine.rb
+- lib/flowengine/rails/version.rb
+- lib/generators/flow_engine/flow/flow_generator.rb
+- lib/generators/flow_engine/flow/templates/flow_definition.rb.tt
+- lib/generators/flow_engine/flow/templates/seed_task.rake.tt
+- lib/generators/flow_engine/install/install_generator.rb
+- lib/generators/flow_engine/install/templates/initializer.rb
+- log/.gitkeep
+- sig/flowengine/rails.rbs
+homepage: https://github.com/kigster/flowengine-rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/flowengine-rails
+  source_code_uri: https://github.com/kigster/flowengine-rails
+  changelog_uri: https://github.com/kigster/flowengine-rails/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: Rails Engine adapter for FlowEngine — persistence, web wizard UI, and admin
+  CRUD
+test_files: []