fgof-devloop Public

Notifications Fork 0 Star 0
trunk
Branches trunk Tags v0.1.0
1 Branches 1 Tags
Go to file T
Code
mfwolffe Use tagged process dependency
be8dce4 21 Commits
.github Add devloop release examples
example Add devloop release examples
src Resolve devloop audit findings
test Resolve devloop audit findings
.gitignore Ignore local docs
README.md Use tagged process dependency
fpm.toml Use tagged process dependency

fgof-devloop

Watch-driven rebuild, restart, and smoke-loop helpers for modern Fortran tools.

fgof-devloop is intended to be a small standalone library for the reusable parts of development loops: deciding when file changes should trigger work, tracking run cycles, modeling restart policy, and layering those decisions over fgof-watch, fgof-process, and fgof-jobs.

It is part of the FortranGoingOnForty lib-modules catalog, but it is intended to stand on its own as a normal fpm package.

Current v1 target:

  • stable dev-loop option and state types
  • deterministic cycle and restart decision helpers
  • watch-event shaping that can consume fgof-watch
  • process-runner integration that can supervise rebuild and run commands
  • long-running service/job restart planning over fgof-jobs
  • examples for command-line tools and local service smoke loops

Status

v0.1.0 is released.

Tracked today:

  • package layout, CI, and standalone repo setup
  • local sprint plan in ignored .docs/sprints/
  • stable option, trigger, cycle, decision, and state types
  • pure run-cycle helpers for start, finish, stop, and restart decisions
  • deterministic failure policy through stop_on_failure and max_failures
  • fgof-watch integration through shaped event summaries and trigger policy
  • loop-owned restart filters for directory events and minimum change counts
  • watch option projection for debounce polls, hidden-path ignores, and directory-event emission
  • fgof-process integration for one-shot build, run, and smoke command supervision
  • command results that retain full process_result output, exit, timeout, and error detail
  • fgof-jobs integration for long-running service ownership, wait observation, cleanup, and restart planning
  • pipeline-aware job observation that preserves terminal member state during group stop/continue events
  • released jobs are treated as unmanaged and will not receive restart/stop/start plans
  • tracked examples for watch-driven command cycles and service restart planning
  • CI coverage for both fpm test --verbose and fpm run --example --all
  • focused model, watch-bridge, process-supervision, job-supervision, and example coverage

Public API Shape

Primary modules:

  • fgof_devloop
  • fgof_devloop_types

Current public procedures:

  • clear_devloop_options
  • clear_devloop_trigger
  • clear_devloop_cycle
  • clear_devloop_decision
  • clear_devloop_watch_summary
  • clear_devloop_command_spec
  • clear_devloop_command_result
  • clear_devloop_supervision_result
  • clear_devloop_job_spec
  • clear_devloop_job_state
  • clear_devloop_job_plan
  • devloop_backend_name
  • clear_devloop_state
  • start_devloop
  • stop_devloop
  • should_start_on_open
  • devloop_start_trigger
  • devloop_change_trigger
  • devloop_manual_trigger
  • devloop_summarize_watch_events
  • devloop_watch_failure_summary
  • devloop_watch_options
  • devloop_watch_trigger
  • devloop_build_command
  • devloop_run_command
  • devloop_smoke_command
  • run_devloop_command
  • run_devloop_cycle
  • devloop_service_job
  • attach_devloop_job
  • attach_devloop_pipeline_members
  • observe_devloop_job
  • release_devloop_job
  • devloop_job_restart_plan
  • begin_devloop_cycle
  • finish_devloop_cycle

Current semantics:

  • devloop_options carries run-on-start, restart-on-change, directory restart, hidden-path ignore, debounce, stop-on-failure, and max-failure policy
  • devloop_trigger records why work should begin, such as start, file change, or manual request
  • devloop_watch_summary condenses fgof-watch event batches into file, directory, create, modify, remove, move, ignored, and failure counters
  • devloop_watch_options() projects dev-loop policy into fgof-watch options for debounce polls, hidden-path filtering, and directory event emission
  • 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
  • devloop_change_trigger() suppresses nonpositive change counts so empty batches cannot start cycles through the lower-level trigger API
  • devloop_build_command(), devloop_run_command(), and devloop_smoke_command() wrap fgof-process commands with loop roles and optional process options
  • run_devloop_command() executes one command spec and preserves the raw process_result, including stdout, stderr, exit code, timeout state, and process error details
  • 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()
  • devloop_service_job() builds a long-running service/job spec backed by fgof-jobs
  • attach_devloop_job() records an already-launched pid/process group and ownership expectations
  • observe_devloop_job() applies fgof-jobs wait results while preserving member-level terminal state
  • 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 and release-on-handoff plans return no stop/start/restart action
  • begin_devloop_cycle() increments the cycle counter and starts work only when the loop is active, idle, and policy permits the trigger
  • finish_devloop_cycle() records success or failure and returns an explicit decision to idle, restart, or stop
  • negative max_failures values normalize to unlimited failures
  • negative debounce_polls values normalize to no debounce
  • Sprint 05 remains model-first: it plans and observes long-running job ownership, while actual spawning/signaling stays in the launcher layer

Dependency

fgof-devloop depends on fgof-watch v0.1.0 for watch-event types and watch option projection, fgof-process v0.1.1 for one-shot process execution, and fgof-jobs v0.1.0 for long-running job ownership and wait-state modeling:

[dependencies]
fgof-jobs = { git = "https://github.com/FortranGoingOnForty/fgof-jobs.git", tag = "v0.1.0" }
fgof-process = { git = "https://github.com/FortranGoingOnForty/fgof-process.git", tag = "v0.1.1" }
fgof-watch = { git = "https://github.com/FortranGoingOnForty/fgof-watch.git", tag = "v0.1.0" }

Build And Test

fpm test
fpm run --example --all

Examples

Tracked examples live in example/ and are intentionally deterministic:

  • watch_cycle_demo.f90 shapes a synthetic watch batch into a trigger, then runs build and smoke commands through fgof-process
  • service_restart_demo.f90 models restart and release behavior for a long-running service using an attached fgof-jobs handle

Supported Platforms

  • macOS
  • Linux

Boundaries

  • focused on reusable development-loop mechanics, not a full CLI app
  • should remain useful on its own even if future tools wrap it with UI policy
  • watch, process, and job integration should stay layered over stable state transitions
  • does not spawn long-running services or send signals directly; callers own launcher policy and use devloop_job_restart_plan() as the planning surface
  • uses tagged dependencies for the released process, watch, and jobs surfaces

License

MIT