easy_flow 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7edfa93c9b14713a7ff4a65d05d6a2a1db3c5f5c53ae915496b0df374ee7b3d5
-  data.tar.gz: 9be1fef6ffb30e8e8063521dbc3ea880fc2957534a9be8fb54694c08316e86f7
+  metadata.gz: 6e277531505d578e7a66331a93c7af61f08d0558bed385af31d173ce500fadf1
+  data.tar.gz: 2a9b83f04a28d3831ae1786766849adb73a44b91d828d6e044d751fd223d1ebf
 SHA512:
-  metadata.gz: d1b72663067985bc5298a8f3ef1cf753b99efe7bc6df10cfda381808a918ebf50bb43286addbe3151b1120c3bc99349717598588d2481d7e35416338371fd4bd
-  data.tar.gz: e4d4eb6618457e868bbd076d95de63bbdec36f222129c7c5ad5207334b754f89d761b356e44ae8e53b018fc694320f79bbb99dd30c61e645c03271f2ac6ac3f6
+  metadata.gz: b4df662a23036aa6b8d70253e980b096dca08f4fad0359cc1b6fc14c31328b70efd77e321c1bb1f7d19476dc215d50ed37157c0d5749893901957c3905bc362f
+  data.tar.gz: f36528a6ea1f1b75c2d76386bf55af3ab1548468590aeb03a0a130f0407f89cf7539e86d170a4bb7ed522a99c9ff120ef93d1b0f00070ffb85f99c6edf8489cc

data/app/models/easy_flow/digest.rb

@@ -65,7 +65,7 @@ module EasyFlow
     end
 
     def next_step(state, times = {})
-      walk(state, times).last
+      walk(state, times)[1]
     end
 
     def output(state, times = {})
@@ -75,6 +75,17 @@ module EasyFlow
       ended.config["output"].presence if step_type(ended)&.ends_here?
     end
 
+    def ended_at_end?(state, times = {})
+      ended = nil
+      _recorded, waiting, = walk(state, times) { |cursor| ended = cursor }
+
+      waiting.nil? && step_type(ended)&.ends_here? || false
+    end
+
+    def stopped_on_loop(state, times = {})
+      walk(state, times)[2]
+    end
+
     def state_on_path(state, times = {})
       state.slice(*walk(state, times).first)
     end
@@ -101,7 +112,7 @@ module EasyFlow
       cursor = entry
 
       while cursor
-        return [ recorded, nil ] if visits[cursor.id].positive? && answers_at_visit[cursor.id] == answered
+        return [ recorded, nil, cursor.id ] if visits[cursor.id].positive? && answers_at_visit[cursor.id] == answered
 
         yield cursor if block_given?
         visits[cursor.id] += 1

data/app/models/easy_flow/run.rb

@@ -38,6 +38,14 @@ module EasyFlow
       digest.next_step(state.transform_keys(&:to_s), completed_at.transform_keys(&:to_s))
     end
 
+    def ended_at_end?
+      digest.ended_at_end?(recorded.transform_keys(&:to_s), completed_at.transform_keys(&:to_s))
+    end
+
+    def stopped_on_loop
+      digest.stopped_on_loop(recorded.transform_keys(&:to_s), completed_at.transform_keys(&:to_s))
+    end
+
     def output
       digest.output(recorded.transform_keys(&:to_s), completed_at.transform_keys(&:to_s))
     end

data/lib/easy_flow/version.rb

@@ -1,3 +1,3 @@
 module EasyFlow
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

data/the_local/agents/easy_flow-develop.md

@@ -1,6 +1,6 @@
 ---
 name: easy_flow-develop
-description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, takes several answers at once, computes a value from earlier answers, records several values under names an admin enters in the step's settings, counts how many times an earlier step was answered so a loop can give up after a number of tries, picks the next branch, or holds the visitor until something outside the flow has happened), branching on whether all or any of several comparisons of earlier answers hold, holding a run until a number of minutes after an earlier answer, the next time of day after it, or a date, branching on the hour, weekday or time an earlier step was completed or on the minutes between two completed steps, reading when each step was completed and when a waiting run will move on, showing a step differently depending on the visitor's stored run, branching on what a visitor ticked on a checklist, moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, letting an admin pick another flow of the same host in a step's settings, adding a step type that starts another flow and works out which flow and version to run from its own settings, adding a step type that starts another flow chosen from the visitor's run, such as its owner or its answers, offering a visitor only the answers to a step that their earlier answers allow, filling in a step that has only one possible answer without asking it, skipping a step that does not apply to a visitor, letting an admin edit a value stored on one of the app's own records from a step's settings on the canvas, serving a host's flows from the app's own controller and routes, starting a visitor's run on a published version of a flow other than the live one, acting when a visitor finishes a flow, acting on the output a visitor's flow ended with, keeping a flow from being published while a step that starts another flow names a flow or version that cannot run or leads back to the flow it sits in, finding the run of another flow that a Flow step started, the run a waiting run is waiting on, and the run that started it, sending a visitor back to the run that started a flow once that flow ends, handling a run whose starting run was removed with its flow, handling a Flow step that cannot start its flow or whose flow ended with no output, taking one file or several from a visitor at a step, showing a step's recorded answer by a label the step type works out, and reading a run's recorded answers and question labels, including every answer ticked on a checklist and every visit's answer when a flow loops back to a question already asked — MUST BE USED instead of hand-rolling questionnaire steps, checkbox lists, file upload steps, branching logic, answer lists filtered by earlier answers, skipped questions, number comparisons, comparisons of two earlier answers, and/or conditions over several comparisons, hard-coded setting options, copying a record's value into a flow and back, answer validation, retry counters, timers or scheduled delays, step completion timestamps, polling or "come back later" pages, flow controllers or answer lookups.
+description: Use PROACTIVELY for adding a step type to easy_flow flows (a step that asks the visitor something, takes several answers at once, computes a value from earlier answers, records several values under names an admin enters in the step's settings, counts how many times an earlier step was answered so a loop can give up after a number of tries, picks the next branch, or holds the visitor until something outside the flow has happened), branching on whether all or any of several comparisons of earlier answers hold, holding a run until a number of minutes after an earlier answer, the next time of day after it, or a date, branching on the hour, weekday or time an earlier step was completed or on the minutes between two completed steps, reading when each step was completed and when a waiting run will move on, showing a step differently depending on the visitor's stored run, branching on what a visitor ticked on a checklist, moving a paused run on once what it waits for has happened, refusing a blank or invalid answer to a step with a message, offering an admin a step setting whose options are read from the app's own records, letting an admin pick another flow of the same host in a step's settings, adding a step type that starts another flow and works out which flow and version to run from its own settings, adding a step type that starts another flow chosen from the visitor's run, such as its owner or its answers, offering a visitor only the answers to a step that their earlier answers allow, filling in a step that has only one possible answer without asking it, skipping a step that does not apply to a visitor, letting an admin edit a value stored on one of the app's own records from a step's settings on the canvas, serving a host's flows from the app's own controller and routes, starting a visitor's run on a published version of a flow other than the live one, acting when a visitor finishes a flow, acting on the output a visitor's flow ended with, telling whether a run ended at an End step or was stopped by a loop that came back with nothing new answered and at which step, keeping a flow from being published while a step that starts another flow names a flow or version that cannot run or leads back to the flow it sits in, finding the run of another flow that a Flow step started, the run a waiting run is waiting on, and the run that started it, sending a visitor back to the run that started a flow once that flow ends, handling a run whose starting run was removed with its flow, handling a Flow step that cannot start its flow or whose flow ended with no output, taking one file or several from a visitor at a step, showing a step's recorded answer by a label the step type works out, and reading a run's recorded answers and question labels, including every answer ticked on a checklist and every visit's answer when a flow loops back to a question already asked — MUST BE USED instead of hand-rolling questionnaire steps, checkbox lists, file upload steps, branching logic, answer lists filtered by earlier answers, skipped questions, number comparisons, comparisons of two earlier answers, and/or conditions over several comparisons, hard-coded setting options, copying a record's value into a flow and back, answer validation, retry counters, timers or scheduled delays, step completion timestamps, polling or "come back later" pages, 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
 ---
@@ -21,7 +21,7 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - `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, started with `EasyFlow::Run.start` on the live version or a chosen published one and pinned to that version, moved on past a waiting step with `advance`, read for the output its flow ended with by `output`, for when each step visit was completed by `completed_at` and for the time a Wait step holds it until by `held_until`, and linked to the runs its Flow steps started by `inner_runs`, to the one it is waiting on by `waiting_on`, and to the run that started it by `parent_run`.
+- `EasyFlow::Run` — the stored record of one visitor's pass through a flow, started with `EasyFlow::Run.start` on the live version or a chosen published one and pinned to that version, moved on past a waiting step with `advance`, read for the output its flow ended with by `output`, for whether it ended at an End step by `ended_at_end?`, for the step a loop stopped it at by `stopped_on_loop`, for when each step visit was completed by `completed_at` and for the time a Wait step holds it until by `held_until`, and linked to the runs its Flow steps started by `inner_runs`, to the one it is waiting on by `waiting_on`, and to the run that started it by `parent_run`.
 - `EasyFlow::QuestionRunner` — reads a flow document: its steps, the next step for a set of answers and the times their steps were completed, the answers on the path taken, and a question's text and an answer's label.
 
 ## How to use it
@@ -500,6 +500,8 @@ Use this when a visitor's run should stop until a set time has passed, such as a
    - `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, routed with the run's own `completed_at`.
    - `run.output` — the text the admin wrote into the output setting of the End step the run ended on, read from the run's pinned version. It is `nil` when the run has not reached an End step, or ended on one whose output was left blank. A flow may have several End steps with a different output on each, so the output says which way the flow ended. Ask the developer what the app does with each output, and what it does when there is none.
+   - `run.ended_at_end?` — `true` when the run is not stopped at a step that awaits input, computes a value or waits, and the last step it reached is of a type that declares `ends_here`, such as the built-in End step, whether or not that step has an output. It is `false` while the run is still going, including while it waits at a Flow step, when a loop stopped it, and when it ended at a step that is not an end, such as a step with no connection leaving it or a `route` value that matches no connection's label. Use it to tell a run that ended at an End step with a blank output from one that stopped anywhere else, since `run.output` is `nil` for both.
+   - `run.stopped_on_loop` — the id of the step a loop came back to when it stopped the run, as a string, the plain step id and never a visit key such as `"tally@2"`, or `nil` when no loop stopped it. A loop stops the run when it comes back to a step already visited with no step that awaits input answered since that step's last visit, such as a loop of Count steps only. The run ends there, and `run.ended_at_end?` is `false`. Ask the developer what the app does with a run a loop stopped, such as showing an admin the step named. Do not pick.
    - `run.advance` — moves the run past every waiting step whose `waits_until` block now returns a truthy value, and past every step that computes a value, and records each result on the run. It stops at the next step that asks the visitor for input, the next waiting step that is not ready, or the end. It does not call `finished`; that is called the next time the visitor loads the run's page. When it stops at a Flow step it starts that step's run, and when it reaches the end of a run a Flow step started it hands the output to the parent run; see "Follow a run into the flow a Flow step started".
 3. To show answers with their question text and answer labels, build a runner from the run's pinned document:
 
@@ -546,7 +548,8 @@ Use this when a visitor's run should stop until a set time has passed, such as a
 - 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.
 - In a flow that loops, a later visit's answer is keyed `<id>@<n>`, so code that reads answers never assumes one answer per step id. A step id may not contain `@`, and a flow with one is refused when published.
-- A loop that comes back to a step with no answer given since the last visit to it ends the flow there, so every loop needs a step that awaits input.
+- A loop that comes back to a step with no answer given since the last visit to it ends the flow there and `run.stopped_on_loop` names that step, so every loop needs a step that awaits input.
+- `run.ended_at_end?` is `true` only for a run whose last step reached is of an `ends_here` type, so a run a loop stopped, or one that ended at a step with no connection to follow, is never counted as ended at an End step.
 - A step's input field is named `answers[<step.id>]` for one value or `answers[<step.id>][]` for several. Any other name is ignored, and a hash is treated as blank.
 - An answer is a string or an array of strings, so code that reads answers never assumes a string. A checklist's answer is always an array.
 - Condition, switch, compare, Compare two values and All of or Any of do not branch on an array answer. Branching on one takes an app step type that defines `route`.

data/the_local/agents/easy_flow-info.md

@@ -1,6 +1,6 @@
 ---
 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, flows that loop back to ask a step again, hosts and the step types each offers its admins, runs and the published version each starts on, each visit a run records with its value and the time the step was completed, and the output a flow gives when it ends, the built-in step types including questions and checklists that can require an answer and explain each answer behind an info button, file upload steps that hand a visitor's file to the app's file store and read it back by its name, and branching on an answer, including one named output of a step that recorded several, on comparing a number with an amount, or on comparing two earlier answers, branching on a list of such comparisons that must all hold or of which any one must hold, branching on the hour, weekday or minute a step was completed, Wait steps that hold a run until a number of minutes or a time of day after an earlier step was completed, or until a date, and are named after what they wait for, the Check again button a visitor sees at a waiting step in a flow that keeps nothing, Count steps that count how often an earlier step was answered so a loop can give up after a number of tries, Flow steps that name another flow, open its canvas when their card is clicked with a button back to the flow it was opened from, start a run of it for the same owner when a stored run reaches them, are flagged when the flow or version they name cannot run or leads back to the flow they sit in, let the waiting run name that inner run, move that run on along the output it ends with, and fail with an error naming the step when its version was taken out of service or its inner run ended with no output, removing a flow and why it is refused while a waiting run depends on it, step types the host app registers, including ones whose outputs are named by the entries an admin lists in one of their settings, ones that start another flow and work out which flow and version to run from their own settings and are named after that flow, or choose it from the run they are in, the answers a host allows a step in a run and the steps it fills in or passes over, the checks they make on an answer, what a step shows a visitor and how that can depend on the visitor's run, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data and settings kept on one of the app's own records.
+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, flows that loop back to ask a step again, a loop that stops a run when nothing new was answered and the step it came back to, whether a run ended at an End step, hosts and the step types each offers its admins, runs and the published version each starts on, each visit a run records with its value and the time the step was completed, and the output a flow gives when it ends, the built-in step types including questions and checklists that can require an answer and explain each answer behind an info button, file upload steps that hand a visitor's file to the app's file store and read it back by its name, and branching on an answer, including one named output of a step that recorded several, on comparing a number with an amount, or on comparing two earlier answers, branching on a list of such comparisons that must all hold or of which any one must hold, branching on the hour, weekday or minute a step was completed, Wait steps that hold a run until a number of minutes or a time of day after an earlier step was completed, or until a date, and are named after what they wait for, the Check again button a visitor sees at a waiting step in a flow that keeps nothing, Count steps that count how often an earlier step was answered so a loop can give up after a number of tries, Flow steps that name another flow, open its canvas when their card is clicked with a button back to the flow it was opened from, start a run of it for the same owner when a stored run reaches them, are flagged when the flow or version they name cannot run or leads back to the flow they sit in, let the waiting run name that inner run, move that run on along the output it ends with, and fail with an error naming the step when its version was taken out of service or its inner run ended with no output, removing a flow and why it is refused while a waiting run depends on it, step types the host app registers, including ones whose outputs are named by the entries an admin lists in one of their settings, ones that start another flow and work out which flow and version to run from their own settings and are named after that flow, or choose it from the run they are in, the answers a host allows a step in a run and the steps it fills in or passes over, the checks they make on an answer, what a step shows a visitor and how that can depend on the visitor's run, and steps that hold a run until something outside the flow has happened, and the settings an admin fills in, including picks whose options come from the app's data and settings kept on one of the app's own records.
 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
 ---
@@ -18,13 +18,13 @@ Reach for it when an app needs a questionnaire, an intake form, or any decision
 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 and the step types each one offers, choosing the default step drawing, setting the file store that keeps uploaded files, the flow checks, and the admin pages.
-- **easy_flow-develop** owns building on it: declaring and registering step types, including ones that read an answer back under a label of their own, ones whose outputs are named by the entries an admin lists in one of their settings, ones that wait, ones whose waiting or routing rule reads the times steps were completed, ones that start another flow, and ones with settings kept on the app's own records, narrowing the answers a host allows a step in a run, moving a run on once what it waits for has happened, serving a host's flows from the app's own controllers and routes, and starting a run on a chosen published version, reading a visitor's run, its answers, the times its steps were completed, the inner run it is waiting on, the time a Wait step is holding it until and the output its flow ended with.
+- **easy_flow-develop** owns building on it: declaring and registering step types, including ones that read an answer back under a label of their own, ones whose outputs are named by the entries an admin lists in one of their settings, ones that wait, ones whose waiting or routing rule reads the times steps were completed, ones that start another flow, and ones with settings kept on the app's own records, narrowing the answers a host allows a step in a run, moving a run on once what it waits for has happened, serving a host's flows from the app's own controllers and routes, and starting a run on a chosen published version, reading a visitor's run, its answers, the times its steps were completed, the inner run it is waiting on, the time a Wait step is holding it until, the output its flow ended with, whether it ended at an End step, and the step a loop came back to when it stopped the run.
 
 ## How to use it
 
 - To get easy_flow running in an app, or to change how it is configured, including which step types a host's admins can add and where uploaded files are kept, use **easy_flow-install**.
 - To ask a visitor for a file, an admin places a file upload step on the canvas, and the app must first have a file store set through **easy_flow-install**.
-- To add a step type, give a step type its own rule for refusing an answer, give it its own way to read an answer back, name a step type's outputs after the entries an admin lists in one of its settings, make what a step shows depend on the visitor's run, hold a run until something outside the flow has happened, make a step type's waiting or routing rule read the times steps were completed, read the time a Wait step is holding a run until, add a step type of the app's own that starts another flow, including one that chooses the flow from the run it is in, limit which answers a step offers in a run from the answers given so far, keep a step's setting on one of the app's own records, put a flow on the app's own pages, start a run on a published version other than the live one, act on what a visitor answered or when each step was completed, or act on the output a visitor's flow ended with, use **easy_flow-develop**.
+- To add a step type, give a step type its own rule for refusing an answer, give it its own way to read an answer back, name a step type's outputs after the entries an admin lists in one of its settings, make what a step shows depend on the visitor's run, hold a run until something outside the flow has happened, make a step type's waiting or routing rule read the times steps were completed, read the time a Wait step is holding a run until, add a step type of the app's own that starts another flow, including one that chooses the flow from the run it is in, limit which answers a step offers in a run from the answers given so far, keep a step's setting on one of the app's own records, put a flow on the app's own pages, start a run on a published version other than the live one, act on what a visitor answered or when each step was completed, act on the output a visitor's flow ended with, or tell a run that ended at an End step from one a loop stopped, use **easy_flow-develop**.
 - To give a flow a different output for each way it can end, no code is needed: an admin fills in the output on each End step on the canvas.
 - To branch a flow on an answer or on a number the visitor gave, no code is needed: an admin places one of the built-in branching steps on the canvas.
 - To branch a flow on how two earlier answers compare, such as whether a second reading is higher than the first, no code is needed: an admin places a Compare two values step on the canvas.
@@ -96,7 +96,8 @@ easy_flow declares no commands of its own for this local. Its surface is split b
 - **Answers** — the recorded values of a run, keyed by visit. The next step is always worked out from these values, their completion times and the connections in the pinned version.
 - **Loop** — a connection that leads back to a step the run has already passed, so that step is visited again. Branching steps read the most recent answer to a step, so a loop ends when an answer sends the run down a different connection. Reading a finished run again follows the same connections it took at the time, since each branching step reads the answers as they stood at that visit.
 - **Visit** — one time a run reaches a step. The first visit is keyed by the step id alone, and each later visit is keyed by the step id, an `@`, and the visit number, such as `size@2`. Every visit's value and completion time are kept, and a finished run lists each one.
-- **Stopped loop** — a run that comes back to a step with no new answer given since its last visit there ends at that point rather than cycling forever. Only answers the visitor gives count, so a loop made only of steps that act on their own stops the first time it comes round.
+- **Stopped loop** — a run that comes back to a step with no new answer given since its last visit there ends at that point rather than cycling forever. Only answers the visitor gives count, so a loop made only of steps that act on their own stops the first time it comes round. A stored run stopped this way names the step the loop came back to, and does not count as having ended at an End step.
+- **Ended at an End step** — whether a stored run's path finished on an End step, or on a step of the app's own type that ends a flow. It does not while the run is still going or held at a step, when a loop stopped it, or when it stopped at a step with no connection to follow.
 - **Reserved `@`** — a step id may not contain `@`, since that mark numbers later visits. A flow holding such a step id is reported as invalid.
 - **Refused answer** — an answer the step's answer check turned down. Nothing is recorded for that step, and the visitor is shown the same step again with the check's message. This works the same whether the flow keeps a stored run or carries its answers in the page.
 - **Blank answer** — a step the visitor leaves blank. On a step whose answer check does not refuse it, such as a question or checklist that is not required, the blank is recorded and the visitor moves on to the next step. This works the same whether the flow keeps a stored run or carries its answers in the page, and every value ticked on a checklist is carried either way.

data/the_local/agents/easy_flow-install.md

@@ -136,4 +136,4 @@ A Rails engine for flows an admin draws on a canvas and a visitor runs one step
 - After setting a host's `offers`, check that the canvas palette on that host's `<mount path>/manage/flows` lists only those step types and End.
 - Taking a step type off a host's `offers` removes it from the palette only. Steps of that type already in the host's flows stay in them and keep running.
 - The initializer runs once at boot, so a change to it needs a server restart.
-- Declaring step types, including settings kept on the app's own records, serving a host's flows from the app's own controllers and routes, and reading runs, answers and the output a flow ended with are out of scope here. They belong to the `easy_flow-develop` local.
+- Declaring step types, including settings kept on the app's own records, serving a host's flows from the app's own controllers and routes, and reading runs, answers, the output a flow ended with, whether a run ended at an End step and the step a loop stopped a run at are out of scope here. They belong to the `easy_flow-develop` local.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_flow
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - tylercschneider