easy_flow 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09da0c518d71ed06c4d63399b2038696d15c770ee0706926bad55f81a3a58a34'
-  data.tar.gz: 68642f79f5418b7db09b3a7274948f8480f7519ca4224546b23bdb94e6e7db0d
+  metadata.gz: 7d14521622c3830ea4e9608d08eaa8b8d90125cd898bdf8aa8547b09a80aa905
+  data.tar.gz: cd223813e0562b015871a7b614fc9ae343a954fd52ec44b06e2197fd6f758297
 SHA512:
-  metadata.gz: 2ae172d8e8851e18042c80217e2163f1e4b3cf829f556c2936ee41f353340b05eea8225d0fc3cd412186adb9c662f36380cbca51b1ef259455ea44e1ea5467f6
-  data.tar.gz: 5069ecd19aafa80210158466d6819233b1485bc6820f4d1f259ebcdb0c067b1fafa94ab72be84210d32acbc0c510d7e8c115cb303c0e304f17d87cbeb3587233
+  metadata.gz: e2b3b92295289c74be0bbde30055366b5c9d59c07378bda7347d723c4e8dc6a74a5fb15681cde91345f35ed17816e46995ceb2f9bc323221e5b7655a0efe320b
+  data.tar.gz: 3f8e757df44027f931efd503d54f1640a486e6cd9b2f56825f4c95b9036d2653731d5318b28ac16de701b93e0861b1bc41d07c4ca9c8192a00cc5cca24e3aad8

data/Rakefile

@@ -4,3 +4,5 @@ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
+
+require "the_local/rake"

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.4.3"
+  VERSION = "0.4.4"
 end

data/the_local/agents/easy_flow-develop.md

@@ -0,0 +1,175 @@
+---
+name: easy_flow-develop
+description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, computes a value from earlier answers, or picks the next branch), serving a host's flows from the app's own controller and routes, acting when a visitor finishes a flow, and reading a run's recorded answers and question labels — MUST BE USED instead of hand-rolling questionnaire steps, branching logic, flow controllers or answer lookups.
+tools: Read, Write, Edit, Grep
+scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
+---
+
+This local follows the steps below exactly and invents none. Where a step names a decision, it asks the developer and does not pick.
+
+## What easy_flow is
+
+A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Each step is an instance of a step type, and the engine ships the question type (a question with a list of answers) plus its own start, end, condition and switch types. Use this local when the app needs a step type of its own, needs a host's flows on its own pages with its own behaviour when a visitor finishes, or needs to read what a visitor answered. It assumes easy_flow is already installed and a host is declared; if not, hand off to `easy_flow-install` first.
+
+## Interface
+
+- `EasyFlow::Step` — a module a class includes to declare a step type with class-level words, registered with `.register`.
+- `EasyFlow.step` — declares and registers a step type in one call from a block of the same words, for a type small enough not to need its own class.
+- `EasyFlow::FlowsController` — the visitor controller; the app subclasses it to serve one host's flows from its own routes and to change what happens at the start, on each step and at the finish.
+- `hosted_by` — class method on a `FlowsController` subclass naming the host whose flows it serves.
+- `routed_by` — class method on a `FlowsController` subclass naming the prefix of the app's own route names that the controller redirects and links to.
+- `EasyFlow::Run` — the stored record of one visitor's pass through a flow, pinned to the version that was live when it started.
+- `EasyFlow::QuestionRunner` — reads a flow document: its steps, the next step for a set of answers, the answers on the path taken, and a question's text and an answer's label.
+
+## How to use it
+
+### Declare a step type
+
+1. Ask the developer what the step does, and which of these it is:
+   - It asks the visitor for input — declare `awaits_input`.
+   - It computes a value from earlier answers with no visitor input — define `process`.
+   - It only picks which connection to follow — define `route`.
+   A type may both `process` and `route`. A type that does none of the three is skipped when a visitor reaches it.
+2. Create the class in the app, for example `app/models/flow_steps/rating.rb`. The class name, underscored, is the type's id (`Rating` becomes `:rating`), and that id is stored in every flow that uses it, so it must not change after admins start using the type:
+
+   ```ruby
+   module FlowSteps
+     class Rating
+       include EasyFlow::Step
+
+       step_name "Rating"
+
+       setting :prompt, type: :string, required: true
+       setting :scale, type: :select, options: %w[5 10], required: true
+
+       output :score, type: :integer, label: "Score"
+
+       names_by :prompt
+       awaits_input
+       drawn_by "flow_steps/rating"
+
+       displays_by { |node| RatingPrompt.new(id: node.id, text: node.config["prompt"], scale: node.config["scale"].to_i) }
+     end
+   end
+   ```
+
+   For a small type with no methods of its own, the block form declares and registers in one call instead of a class and step 3:
+
+   ```ruby
+   EasyFlow.step(:note) do
+     step_name "Note"
+     setting :text, type: :string
+     awaits_input
+   end
+   ```
+
+3. Register each class-based type in `config/initializers/easy_flow.rb` inside `to_prepare`, so it is registered again after a code reload:
+
+   ```ruby
+   Rails.application.config.to_prepare do
+     FlowSteps::Rating.register
+   end
+   ```
+
+   A step whose type is not registered is neither shown nor run as that type.
+4. Use these words to declare the type. Each is called once at class level (or inside the `EasyFlow.step` block):
+   - `step_name "<label>"` — the name admins see on the canvas. Defaults to the id.
+   - `setting :name, type:, label:, options:, required:, limit:, check:, from:, outputs_of:` — a field the admin fills in on the canvas. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, `:select`, `:multi_select`, `:previous_step`, `:from_step`, `:list`. A `:select` or `:multi_select` must pass `options:`, or boot raises `EasyFlow::UnknownFieldType`. A `:list` must take a block of `setting` calls describing one entry. `:previous_step` lets the admin pick an earlier step. `outputs_of: :<setting>` offers the outputs of the step chosen in that setting, and `from: :<setting>` offers the values of the output chosen in that setting; either one makes the type `:from_step`.
+   - `output :name, type:, label:, values:, from:` — a value the step records. `type` is one of `:string`, `:integer`, `:float`, `:boolean`, or boot raises `EasyFlow::UnknownOutputType`. `values:` is an array or a lambda taking the node, listing the values the output can take; the canvas offers these as the connections leaving the step. `from: :<setting>` takes the values from the step chosen in that setting.
+   - `names_by :setting` or `names_by { |node| ... }` — what the step is called on the canvas, from a setting or computed.
+   - `awaits_input` — the visitor is shown this step and must answer it.
+   - `ends_here` / `begins_here` — marks the type as an end or a start of a flow.
+   - `displays_by { |node| ... }` — builds the object handed to the step's partial as the local `step`. Without it the partial receives the node itself.
+   - `drawn_by "<partial>"` — the partial that draws this type for a visitor. Without it the host's default drawing is used, which expects `step.id`, `step.text` and `step.choices`, so a type with its own display shape needs its own partial.
+5. For a type that computes or routes, define instance methods on the class (or `process { |node, state| ... }` / `route { |node, state| ... }` in the block form):
+
+   ```ruby
+   def process(node, state)
+     state[node.config["step"]].to_i * 2
+   end
+
+   def route(node, state)
+     state[node.config["step"]] == node.config["answer"]
+   end
+   ```
+
+   - `node` has `id`, `type` and `config`; `config` is a hash of the admin's settings with string keys.
+   - `state` is the answers recorded so far, keyed by step id as strings.
+   - `process` returns the value recorded under this step's id. It runs as soon as a visitor reaches the step, before the next step is shown.
+   - `route` returns the value that picks the connection to follow; it is compared as a string with the value each leaving connection is labelled with. Returning `nil` follows the first connection.
+6. For a type that awaits input, write the partial named in `drawn_by`, for example `app/views/flow_steps/_rating.html.erb`. It receives the display object as `step`. It renders only the input, since the page supplies the form, the Next button and the Back button. The input must be named `answers[<step id>]`, or the answer is not recorded:
+
+   ```erb
+   <%= label_tag "answers[#{step.id}]", step.text %>
+   <%= number_field_tag "answers[#{step.id}]", nil, in: 1..step.scale %>
+   ```
+
+7. Restart the server, open a flow on the canvas and check the type is offered, its settings show, and a preview walks through it.
+
+### Serve a host's flows from the app's own controller
+
+1. Ask the developer which host this controller serves, what path the visitor pages live under, and what should happen when a visitor finishes. Do not choose the finish behaviour for them.
+2. Add the routes in `config/routes.rb`. The names must be the prefix followed by `_flow`, `_flow_step`, `_flow_runs` and `_run`, because the controller builds every link and redirect from those four:
+
+   ```ruby
+   get   "intake/:slug",      to: "intake_flows#show",  as: :intake_flow
+   get   "intake/:slug/step", to: "intake_flows#step",  as: :intake_flow_step
+   post  "intake/:slug/runs", to: "intake_flows#start", as: :intake_flow_runs
+   get   "intake/runs/:id",   to: "intake_flows#step",  as: :intake_run
+   patch "intake/runs/:id",   to: "intake_flows#update"
+   ```
+
+3. Create the controller, naming the host with `hosted_by` and the route prefix with `routed_by`:
+
+   ```ruby
+   class IntakeFlowsController < EasyFlow::FlowsController
+     hosted_by :intake
+     routed_by :intake
+
+     private
+
+     def finished(answers, run)
+       redirect_to main_app.intake_summary_path(run)
+     end
+   end
+   ```
+
+   The controller inherits from the base controller set at install, uses the host's layout, visitor authorization and refusal methods, and only finds flows that belong to the named host. Pages it does not override use the engine's own views.
+4. Override only the private methods the developer's answers call for:
+   - `finished(answers, run)` — called when the visitor reaches the end. `answers` is the answers on the path taken, keyed by step id as symbols. `run` is the stored `EasyFlow::Run`, or `nil` when the flow keeps no record. It must render or redirect. Default: the engine's completion page.
+   - `start_run(flow)` — creates the run when a visitor starts a flow that saves each step. Call `super` and change the run it returns, for example to set its `owner` or `label`.
+   - `runner_for(definition)` — returns the runner used for each step. Return a subclass of `EasyFlow::QuestionRunner` to change what the step and completion pages read from it.
+5. Visit `/<path>/<slug>` for a published flow and walk it to the end.
+
+### Read a run and its answers
+
+1. Find runs scoped to one host so one host never sees another's: `EasyFlow::Run.joins(:flow).where(easy_flow_definitions: { host: "intake" })`.
+2. Read from a run:
+   - `run.recorded` — the answers so far, a hash keyed by step id as symbols.
+   - `run.flow` — the flow it belongs to.
+   - `run.owner` — the optional record the run belongs to, polymorphic, set by the app. `run.label` and `run.status` are free string columns for the app's own use.
+   - `run.pinned_definition` — the flow document of the version the run started on.
+   - `run.next_step(answers)` and `run.walked(answers)` — the next step, and the answers on the path taken, for a set of answers against that pinned version.
+3. To show answers with their question text and answer labels, build a runner from the run's pinned document:
+
+   ```ruby
+   runner = EasyFlow::QuestionRunner.new(run.pinned_definition)
+   runner.state_on_path(run.recorded).each do |step_id, value|
+     puts "#{runner.question_text(step_id)}: #{runner.choice_label(step_id, value)}"
+   end
+   ```
+
+   - `state_on_path(answers)` — only the answers on the path the visitor actually took, dropping answers left behind by going back.
+   - `question_text(id)` — the text of a question step. It returns `nil` for a step of any other type.
+   - `choice_label(id, value)` — the label of the chosen answer, or the value itself when there is no label.
+   - `steps`, `step(id)`, `next_step(answers)`, `steps_on_path(answers)`, `slug` and `headline` read the rest of the document.
+
+## Conventions
+
+- A step type's id comes from its class name or the id passed to `EasyFlow.step`, and it is stored in flow documents, so renaming the class or id breaks every flow that uses it.
+- Register class-based step types inside `to_prepare`. A type registered anywhere else is lost on code reload in development.
+- Always read a run against `run.pinned_definition`, never the flow's live version, since a run keeps the version it started on after a new one is published.
+- Always look flows and runs up through a host.
+- A step's input field is named `answers[<step id>]`. Any other name is ignored.
+- A `FlowsController` subclass needs all four named routes for its prefix; a missing one raises when the visitor is linked or redirected to it.
+- The engine installs, mounts and configures hosts, layouts, the default drawing and checks through `easy_flow-install`, not here.

data/the_local/agents/easy_flow-info.md

@@ -0,0 +1,42 @@
+---
+name: easy_flow-info
+description: Use to learn what easy_flow offers — guided flows an admin draws on a canvas and a visitor runs one step at a time, versioned documents of steps and connections, hosts, runs, and step types the host app registers.
+tools: Read
+scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
+---
+
+This local explains easy_flow and the words it uses. It makes no changes and gives no steps.
+
+## What easy_flow is
+
+easy_flow is a Rails engine for guided, branching flows. An admin builds a flow on a canvas by placing steps and connecting them, previews it, and publishes it. A visitor then walks the published flow one step at a time, and each answer decides which step comes next.
+
+Reach for it when an app needs a questionnaire, an intake form, or any decision path that an admin should be able to change without a deploy. The engine ships one step type, a question with a list of answers. Anything else a flow needs to ask or do is a step type the app declares itself.
+
+## Interface
+
+easy_flow declares no commands of its own for this local. Its surface is split between the other two:
+
+- **easy_flow-install** owns putting the engine into an app: its migrations, mounting it, choosing the controller it inherits from, naming hosts, choosing the canvas drawing, turning on optional checks, and the admin pages.
+- **easy_flow-develop** owns building on it: declaring and registering step types, serving a host's flows from the app's own controllers and routes, and reading a visitor's run and answers.
+
+## How to use it
+
+- To get easy_flow running in an app, or to change how it is configured, use **easy_flow-install**.
+- To add a step type, put a flow on the app's own pages, or act on what a visitor answered, use **easy_flow-develop**.
+- If the question is only what a word below means, this page is the answer.
+
+## Conventions
+
+- **Flow** — one guided path, found by its slug. It holds a working document the admin edits and a list of versions.
+- **Document** — the flow's content: its steps (nodes), the connections between them (edges), a headline and a slug.
+- **Version** — a numbered snapshot of the document. A version is a draft until it is published, and a flow has at most one live version at a time.
+- **Canvas** — the admin screen where steps are added, configured, moved, removed and connected, with undo and redo. Publishing happens there.
+- **Preview** — an admin walking the current flow without starting a stored run.
+- **Step type** — what a kind of step is: its display name, its settings (the fields an admin fills in), its outputs (the values it records), and whether it waits for the visitor or acts on its own. A step that acts on its own processes the answers so far and records a result, and a step type may also decide its own routing.
+- **Question** — the built-in step type: a question text and a list of answers, each with a value, a label and a weight.
+- **Registry** — the list of step types the app has registered. A step whose type is not registered is not shown or run as that type.
+- **Host** — a named part of the app that owns a set of flows. A host sets the visitor layout and the admin layout, how admins are authenticated, how visitors are authorized, and how a refusal is answered. Flows are always looked up through a host, so one host never sees another's flows.
+- **Run** — one visitor's pass through a flow. A run is pinned to the version that was live when it started, so publishing a new version does not change a run already under way. It records each answer by step id, and going back discards the last answer on the path.
+- **Answers** — the recorded state of a run, keyed by step id. The next step is always worked out from these answers and the connections in the pinned version.
+- **Checks** — optional warnings on a flow's shape an app can turn on: an answer value no connection routes, a path nothing follows, and a step that leads nowhere.

data/the_local/agents/easy_flow-install.md

@@ -0,0 +1,78 @@
+---
+name: easy_flow-install
+description: Use to hook easy_flow into a project — copying and running its migrations, mounting the engine for each host, setting the controller it inherits from, declaring hosts with their layouts and access methods, choosing the default step drawing, turning on optional checks, and reaching the admin pages.
+tools: Bash, Read, Edit
+scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
+---
+
+This local follows the steps below exactly and invents none. Where a step names a decision, it asks the developer and does not pick.
+
+## What easy_flow is
+
+A Rails engine for flows an admin draws on a canvas and a visitor runs one step at a time. Hook it in when a Rails 8.1 app needs questionnaires, intake forms or decision paths that admins change without a deploy.
+
+## Interface
+
+- `bin/rails easy_flow:install:migrations` — copies the engine's migrations into the host's `db/migrate`, creating the flow, version and run tables.
+- `mount EasyFlow::Engine` — the route that serves one host's visitor pages and admin pages under a path, with the host named in `defaults: { easy_flow_host: "<host>" }`.
+- `EasyFlow.base_controller=` — the name, as a string, of the host controller every engine controller inherits from. Defaults to `"ActionController::Base"`.
+- `EasyFlow.host` — declares a named host with its visitor layout, admin layout, admin authentication method, visitor authorization method and refusal method.
+- `EasyFlow.draws_with` — the partial that draws a visitor's step when the step's type names none. Defaults to the engine's own `easy_flow/steps/choosing`.
+- `EasyFlow.check` — turns on an optional flow check: `:unrouted_value`, `:unfollowed_path` or `:dead_end`.
+- `/manage/flows` — the admin pages, under each mount path, where flows are listed, created, drawn on the canvas, previewed and published.
+
+## How to use it
+
+1. Confirm the app has Keystone UI installed (`keystone_ui` in the Gemfile). easy_flow's controllers use its helpers and it is not pulled in by easy_flow. If it is missing, stop and hand off to the `keystone_ui-install` local before continuing.
+2. Add `gem "easy_flow"` to the host's `Gemfile` and run `bundle install`.
+3. Run `bin/rails easy_flow:install:migrations`, then `bin/rails db:migrate`. This writes four migrations into `db/migrate` and updates `db/schema.rb`.
+4. Ask the developer which hosts the app needs. A host is one part of the app that owns its own set of flows, and one host never sees another's flows. Ask for each host's name and the path it is served under.
+5. Ask the developer which controller the engine should inherit from. Choosing `"ApplicationController"` gives the engine the app's own authentication methods and helpers. Create `config/initializers/easy_flow.rb` and set it on the first line:
+
+   ```ruby
+   EasyFlow.base_controller = "ApplicationController"
+   ```
+
+6. In the same initializer, declare each host. Every setting is optional. Ask the developer for each value and leave out any they do not want:
+
+   ```ruby
+   EasyFlow.host(:console) do |host|
+     host.layout = "application"
+     host.admin_layout = "admin"
+     host.admin_authentication_method = :authenticate_admin!
+     host.visitor_authorization_method = :easy_flow_visitor_permitted?
+     host.refusal_method = :refuse_flow
+   end
+   ```
+
+   - `layout` — the visitor layout. Defaults to the engine's bare layout, which loads no stylesheet, so a styled app almost always sets it.
+   - `admin_layout` — the admin layout. Defaults to `"application"`. It must call `yield :head` inside `<head>`, or the canvas scripts do not load.
+   - `admin_authentication_method` — a method on the base controller, called with no arguments before every admin page. With none set, the admin pages are open to anyone.
+   - `visitor_authorization_method` — a method on the base controller, called with the flow, returning true when the visitor may run it. With none set, every visitor is refused.
+   - `refusal_method` — a method on the base controller, called with the refusal error when a visitor is refused or a flow is unpublished or withdrawn. With none set, the response is `404 Not Found`.
+
+   Each method named here must exist on the base controller. Ask the developer to point at it or write it. Do not invent its logic.
+7. Mount the engine in `config/routes.rb`, once per host. The host name in `defaults` must match a name declared in step 6. When there is more than one mount, give each an `as:` name:
+
+   ```ruby
+   mount EasyFlow::Engine => "/flows", defaults: { easy_flow_host: "flows" }
+   mount EasyFlow::Engine => "/console", as: :console_flows, defaults: { easy_flow_host: "console" }
+   ```
+
+   A mount whose host name is not declared serves no flows, and its admin pages return `404 Not Found`.
+8. Ask the developer whether visitors' steps should be drawn with the engine's own partial or with one from the app. For the app's own, create a partial, for example `app/views/steps/_step.html.erb`, which receives the step as the local `step`. Then add to the initializer:
+
+   ```ruby
+   EasyFlow.draws_with("steps/step")
+   ```
+
+9. Leave `EasyFlow.check` out unless the developer asks for it. The engine already turns on `:unrouted_value`, `:unfollowed_path` and `:dead_end` at boot. Any other name raises `EasyFlow::UnknownCheck` when the app boots.
+10. Start the server and open `<mount path>/manage/flows` for each host.
+
+## Conventions
+
+- After install, check that `<mount path>/manage/flows` shows the flow list and that a new flow opens on the canvas. If the canvas is blank, check that the admin layout calls `yield :head`.
+- After publishing a flow, check that `<mount path>/<slug>` shows it to a visitor who passes the host's visitor authorization method.
+- After upgrading easy_flow, run `bin/rails easy_flow:install:migrations` again and then `bin/rails db:migrate`. Only migrations the app does not already have are copied.
+- The initializer runs once at boot, so a change to it needs a server restart.
+- Declaring step types, serving a host's flows from the app's own controllers and routes, and reading runs and answers are out of scope here. They belong to the `easy_flow-develop` local.

data/the_local/interface.yml

@@ -0,0 +1,40 @@
+scope: guided flows — versioned documents of steps and the connections between them, drawn on a canvas by an admin and run by a visitor one step at a time, with step types the host registers
+
+install:
+  - bin/rails easy_flow:install:migrations
+  - mount EasyFlow::Engine
+  - EasyFlow.base_controller=
+  - EasyFlow.host
+  - EasyFlow.draws_with
+  - EasyFlow.check
+  - /manage/flows
+
+develop:
+  - EasyFlow::Step
+  - EasyFlow.step
+  - EasyFlow::FlowsController
+  - hosted_by
+  - routed_by
+  - EasyFlow::Run
+  - EasyFlow::QuestionRunner
+
+sources:
+  - lib/easy_flow.rb
+  - lib/easy_flow/engine.rb
+  - lib/easy_flow/host.rb
+  - lib/easy_flow/host_routes.rb
+  - app/controllers/concerns/easy_flow/hosted.rb
+  - app/controllers/easy_flow/application_controller.rb
+  - app/controllers/easy_flow/flows_controller.rb
+  - app/controllers/easy_flow/manage/base_controller.rb
+  - app/models/easy_flow/step.rb
+  - app/models/easy_flow/step_type/declaration.rb
+  - app/models/easy_flow/steps/question.rb
+  - app/models/easy_flow/run.rb
+  - app/models/easy_flow/runner.rb
+  - app/models/easy_flow/question_runner.rb
+  - config/routes.rb
+  - db/migrate/20260924120000_create_easy_flow_definitions.rb
+  - db/migrate/20260924120100_create_easy_flow_versions.rb
+  - db/migrate/20260924120200_create_easy_flow_runs.rb
+  - db/migrate/20260924130000_add_host_to_easy_flow_definitions.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - tylercschneider
@@ -140,6 +140,10 @@ files:
 - lib/easy_flow/host_routes.rb
 - lib/easy_flow/unset_host.rb
 - lib/easy_flow/version.rb
+- the_local/agents/easy_flow-develop.md
+- the_local/agents/easy_flow-info.md
+- the_local/agents/easy_flow-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/easy_flow
 licenses:
 - MIT