Add workflow triggers for downstream orchestration

Author: pasunboneleve

README.md

@@ -194,6 +194,23 @@ Repeated setup can be factored into helper workflows and reused with
 `run_workflow`, for example a `publish_post_url` workflow that waits for
 the tunnel and then writes the derived URL.
 
+Downstream orchestration should usually be declared with workflow
+`triggers`, so users can read directly what a successful workflow
+causes next:
+
+```toml
+[workflow.css]
+steps = [
+  { action = "run_hook", hook = "build_css" },
+]
+triggers = ["browser_reload"]
+
+[workflow.browser_reload]
+steps = [
+  { action = "notify_reload" },
+]
+```
+
 Workflows can also trigger a generic browser refresh after successful
 rebuild/restart steps:
 

docs/behavior.md

@@ -66,6 +66,7 @@ Workflows run step by step, in order.
 
 - A step must finish successfully before the next one begins.
 - `run_workflow` executes another named workflow inline.
+- `triggers` run downstream workflows after the workflow succeeds.
 - Recursive workflow graphs are rejected at config-validation time.
 - `write_state` renders `{{state_key}}` templates against the current
   in-memory session state.
@@ -233,6 +234,7 @@ output-derived updates.
   workflow runs triggered by watches or startup execution.
 - Nested `run_workflow` calls reuse the same session state without
   overwriting the top-level change context.
+- Triggered workflows inherit that same top-level change context.
 
 ## Shutdown
 

docs/configuration.md

@@ -293,6 +293,36 @@ steps = [
 ]
 ```
 
+### Workflow triggers
+
+`triggers` declares downstream workflows to run after the workflow's own
+`steps` complete successfully.
+
+```toml
+[workflow.css]
+steps = [
+  { action = "run_hook", hook = "build_css" },
+]
+triggers = ["browser_reload"]
+
+[workflow.browser_reload]
+steps = [
+  { action = "notify_reload" },
+]
+```
+
+Use `triggers` for orchestration that should happen after a workflow
+finishes. Keep `run_workflow` for inline control flow inside a workflow's
+own steps.
+
+Triggered workflows are deduplicated across a single execution. If the
+same workflow is reached through two trigger paths, `devloop` runs it
+once, from the first path that reaches it.
+
+`devloop` rejects configs where a direct trigger target is also reachable
+through a `run_workflow` path in the same execution tree, because that
+would make ordering and duplication ambiguous.
+
 ### Workflow actions
 
 - `start_process`
@@ -306,6 +336,11 @@ steps = [
 - `log`
 - `notify_reload`
 
+### Workflow fields
+
+- `steps`: ordered actions to execute for the workflow itself
+- `triggers`: downstream workflows to run after `steps` succeed
+
 ### `write_state`
 
 ```toml
@@ -374,6 +409,11 @@ steps = [
 steps = [
   { action = "restart_process", process = "server" },
   { action = "wait_for_process", process = "server" },
+]
+triggers = ["browser_reload"]
+
+[workflow.browser_reload]
+steps = [
   { action = "notify_reload" },
 ]
 ```

examples/blog/devloop.toml

@@ -14,10 +14,9 @@ workflow = "rust"
 paths = ["content/**/*.md", "content/**/*.html"]
 workflow = "content"
 
-[process.css_watch]
-command = ["tailwindcss", "-i", "tailwind.css", "-o", "content/static/tailwind.css", "--watch=always"]
-cwd = "."
-autostart = false
+[watch.css]
+paths = ["tailwind.css"]
+workflow = "css"
 
 [process.server]
 command = ["cargo", "run"]
@@ -70,10 +69,9 @@ steps = [
 
 [workflow.startup]
 steps = [
-  { action = "start_process", process = "css_watch" },
+  { action = "run_hook", hook = "build_css" },
   { action = "start_process", process = "server" },
   { action = "wait_for_process", process = "server" },
-  { action = "run_hook", hook = "build_css" },
   { action = "run_hook", hook = "current_browser_path" },
   { action = "start_process", process = "tunnel" },
   { action = "run_workflow", workflow = "publish_post_url" },
@@ -87,13 +85,24 @@ steps = [
   { action = "run_hook", hook = "current_browser_path" },
   { action = "restart_process", process = "tunnel" },
   { action = "run_workflow", workflow = "publish_post_url" },
-  { action = "notify_reload" },
 ]
+triggers = ["browser_reload"]
 
 [workflow.content]
 steps = [
   { action = "run_hook", hook = "current_browser_path" },
   { action = "restart_process", process = "tunnel" },
   { action = "run_workflow", workflow = "publish_post_url" },
+]
+triggers = ["browser_reload"]
+
+[workflow.css]
+steps = [
+  { action = "run_hook", hook = "build_css" },
+]
+triggers = ["browser_reload"]
+
+[workflow.browser_reload]
+steps = [
   { action = "notify_reload" },
 ]

src/browser_reload.rs

@@ -169,6 +169,7 @@ mod tests {
             "rust".into(),
             WorkflowSpec {
                 steps: vec![WorkflowStep::NotifyReload],
+                triggers: vec![],
             },
         );