@@ -4,8 +4,8 @@ Watch-driven rebuild, restart, and smoke-loop helpers for modern Fortran tools. |
| 4 | | 4 | |
| 5 | `fgof-devloop` is intended to be a small standalone library for the reusable | 5 | `fgof-devloop` is intended to be a small standalone library for the reusable |
| 6 | parts of development loops: deciding when file changes should trigger work, | 6 | parts of development loops: deciding when file changes should trigger work, |
| 7 | -tracking run cycles, modeling restart policy, and eventually wiring those | 7 | +tracking run cycles, modeling restart policy, and layering those decisions |
| 8 | -decisions to `fgof-watch`, `fgof-process`, and `fgof-jobs`. | 8 | +over `fgof-watch`, `fgof-process`, and `fgof-jobs`. |
| 9 | | 9 | |
| 10 | It is part of the [FortranGoingOnForty lib-modules](https://github.com/FortranGoingOnForty/lib-modules) | 10 | It is part of the [FortranGoingOnForty lib-modules](https://github.com/FortranGoingOnForty/lib-modules) |
| 11 | catalog, but it is intended to stand on its own as a normal `fpm` package. | 11 | catalog, but it is intended to stand on its own as a normal `fpm` package. |
@@ -16,11 +16,12 @@ Current v1 target: |
| 16 | - deterministic cycle and restart decision helpers | 16 | - deterministic cycle and restart decision helpers |
| 17 | - watch-event shaping that can consume `fgof-watch` | 17 | - watch-event shaping that can consume `fgof-watch` |
| 18 | - process-runner integration that can supervise rebuild and run commands | 18 | - process-runner integration that can supervise rebuild and run commands |
| | 19 | +- long-running service/job restart planning over `fgof-jobs` |
| 19 | - examples for command-line tools and local service smoke loops | 20 | - examples for command-line tools and local service smoke loops |
| 20 | | 21 | |
| 21 | ## Status | 22 | ## Status |
| 22 | | 23 | |
| 23 | -Sprint 04 is in place. | 24 | +Sprint 05 is in place. |
| 24 | | 25 | |
| 25 | Tracked today: | 26 | Tracked today: |
| 26 | | 27 | |
@@ -36,7 +37,10 @@ Tracked today: |
| 36 | - command results that retain full `process_result` output, exit, timeout, and error detail | 37 | - command results that retain full `process_result` output, exit, timeout, and error detail |
| 37 | - `fgof-jobs` integration for long-running service ownership, wait observation, cleanup, and restart planning | 38 | - `fgof-jobs` integration for long-running service ownership, wait observation, cleanup, and restart planning |
| 38 | - pipeline-aware job observation that preserves terminal member state during group stop/continue events | 39 | - pipeline-aware job observation that preserves terminal member state during group stop/continue events |
| 39 | -- focused model, watch-bridge, process-supervision, and job-supervision coverage in `fpm test` | 40 | +- released jobs are treated as unmanaged and will not receive restart/stop/start plans |
| | 41 | +- tracked examples for watch-driven command cycles and service restart planning |
| | 42 | +- CI coverage for both `fpm test --verbose` and `fpm run --example --all` |
| | 43 | +- focused model, watch-bridge, process-supervision, job-supervision, and example coverage |
| 40 | | 44 | |
| 41 | ## Public API Shape | 45 | ## Public API Shape |
| 42 | | 46 | |
@@ -90,19 +94,19 @@ Current semantics: |
| 90 | - `devloop_trigger` records why work should begin, such as start, file change, or manual request | 94 | - `devloop_trigger` records why work should begin, such as start, file change, or manual request |
| 91 | - `devloop_watch_summary` condenses `fgof-watch` event batches into file, directory, create, modify, remove, move, ignored, and failure counters | 95 | - `devloop_watch_summary` condenses `fgof-watch` event batches into file, directory, create, modify, remove, move, ignored, and failure counters |
| 92 | - `devloop_watch_options()` projects dev-loop policy into `fgof-watch` options for debounce polls, hidden-path filtering, and directory event emission | 96 | - `devloop_watch_options()` projects dev-loop policy into `fgof-watch` options for debounce polls, hidden-path filtering, and directory event emission |
| 93 | -- `devloop_watch_trigger()` turns successful watch summaries into change triggers while suppressing watcher failures, empty batches, directory-only batches when disabled, and batches below `min_restart_changes` | 97 | +- `devloop_watch_trigger()` turns successful watch summaries into change triggers while suppressing watcher failures, disabled restart-on-change policy, empty batches, directory-only batches when disabled, and batches below `min_restart_changes` |
| 94 | - `devloop_build_command()`, `devloop_run_command()`, and `devloop_smoke_command()` wrap `fgof-process` commands with loop roles and optional process options | 98 | - `devloop_build_command()`, `devloop_run_command()`, and `devloop_smoke_command()` wrap `fgof-process` commands with loop roles and optional process options |
| 95 | - `run_devloop_command()` executes one command spec and preserves the raw `process_result`, including stdout, stderr, exit code, timeout state, and process error details | 99 | - `run_devloop_command()` executes one command spec and preserves the raw `process_result`, including stdout, stderr, exit code, timeout state, and process error details |
| 96 | - `run_devloop_cycle()` starts a cycle, executes enabled build/run/smoke specs in order, skips later specs after the first failure, and feeds the outcome into `finish_devloop_cycle()` | 100 | - `run_devloop_cycle()` starts a cycle, executes enabled build/run/smoke specs in order, skips later specs after the first failure, and feeds the outcome into `finish_devloop_cycle()` |
| 97 | - `devloop_service_job()` builds a long-running service/job spec backed by `fgof-jobs` | 101 | - `devloop_service_job()` builds a long-running service/job spec backed by `fgof-jobs` |
| 98 | - `attach_devloop_job()` records an already-launched pid/process group and ownership expectations | 102 | - `attach_devloop_job()` records an already-launched pid/process group and ownership expectations |
| 99 | - `observe_devloop_job()` applies `fgof-jobs` wait results while preserving member-level terminal state | 103 | - `observe_devloop_job()` applies `fgof-jobs` wait results while preserving member-level terminal state |
| 100 | -- `devloop_job_restart_plan()` models whether a watched change should stop, start, restart, release, or require terminal handoff for a long-running job | 104 | +- `devloop_job_restart_plan()` models whether a watched change should stop, start, restart, release, or require terminal handoff for a long-running job; released jobs return no action |
| 101 | - `begin_devloop_cycle()` increments the cycle counter and starts work only when the loop is active, idle, and policy permits the trigger | 105 | - `begin_devloop_cycle()` increments the cycle counter and starts work only when the loop is active, idle, and policy permits the trigger |
| 102 | - `finish_devloop_cycle()` records success or failure and returns an explicit decision to idle, restart, or stop | 106 | - `finish_devloop_cycle()` records success or failure and returns an explicit decision to idle, restart, or stop |
| 103 | - negative `max_failures` values normalize to unlimited failures | 107 | - negative `max_failures` values normalize to unlimited failures |
| 104 | - negative `debounce_polls` values normalize to no debounce | 108 | - negative `debounce_polls` values normalize to no debounce |
| 105 | -- Sprint 04 remains model-first: it plans and observes long-running job ownership, while actual spawning/signaling stays in the launcher layer | 109 | +- Sprint 05 remains model-first: it plans and observes long-running job ownership, while actual spawning/signaling stays in the launcher layer |
| 106 | | 110 | |
| 107 | ## Dependency | 111 | ## Dependency |
| 108 | | 112 | |
@@ -122,8 +126,16 @@ fgof-watch = { git = "https://github.com/FortranGoingOnForty/fgof-watch.git", ta |
| 122 | | 126 | |
| 123 | ```bash | 127 | ```bash |
| 124 | fpm test | 128 | fpm test |
| | 129 | +fpm run --example --all |
| 125 | ``` | 130 | ``` |
| 126 | | 131 | |
| | 132 | +## Examples |
| | 133 | + |
| | 134 | +Tracked examples live in `example/` and are intentionally deterministic: |
| | 135 | + |
| | 136 | +- `watch_cycle_demo.f90` shapes a synthetic watch batch into a trigger, then runs build and smoke commands through `fgof-process` |
| | 137 | +- `service_restart_demo.f90` models restart and release behavior for a long-running service using an attached `fgof-jobs` handle |
| | 138 | + |
| 127 | ## Supported Platforms | 139 | ## Supported Platforms |
| 128 | | 140 | |
| 129 | - macOS | 141 | - macOS |
@@ -135,6 +147,10 @@ fpm test |
| 135 | - should remain useful on its own even if future tools wrap it with UI policy | 147 | - should remain useful on its own even if future tools wrap it with UI policy |
| 136 | - watch, process, and job integration should stay layered over stable state | 148 | - watch, process, and job integration should stay layered over stable state |
| 137 | transitions | 149 | transitions |
| | 150 | +- does not spawn long-running services or send signals directly; callers own |
| | 151 | + launcher policy and use `devloop_job_restart_plan()` as the planning surface |
| | 152 | +- uses a pinned `fgof-process` commit until the next process patch release tags |
| | 153 | + the line-wrapping CI fix |
| 138 | | 154 | |
| 139 | ## License | 155 | ## License |
| 140 | | 156 | |