Skip to content
src.fastware.supervise
Updated Edit
On this page

Process supervision for ``fastware dev``: pre-spawn gates, health-gated readiness, backend and Vite topology ordering, and graceful process-group teardown.

#src.fastware.supervise

#src.fastware.supervise

Process supervision for the fastware dev CLI.

Provides :class:DevProcess (a single supervised child in its own process group, with graceful-then-kill teardown) and the orchestration that turns a validated :class:~fastware.devconfig.DevConfig into a running dev environment:

  1. pre-spawn gates (must pass before anything spawns),
  2. ordered, health-gated aux services,
  3. the topology-ordered vite + backend pair with readiness probes,
  4. a supervise loop that, on any component death, tears the rest down in reverse

order and exits non-zero naming the dead component.

Daemon mode detaches the whole supervisor and registers it in the Phase 11 instance registry (entry name "<app-name>-dev"), which dev status and dev stop read.

#DevRunError

Base class for dev-run failures.

#PreSpawnGateError

A pre-spawn gate did not pass; nothing was spawned.

#ReadinessError

A component did not become ready within its timeout.

#PortCollisionError

A required port is already in use.

#SWModeConflictError

The resolved in-process app is configured with sw_mode='cache'.

#ComponentDied

A supervised component exited; the environment was torn down.

#_http_answers

python
def _http_answers(url: str, timeout: float) -> bool

True if url answers at the HTTP level (any status), else False.

#run_pre_spawn_gates

python
def run_pre_spawn_gates(cfg: DevConfig) -> None

Run every pre-spawn gate; raise :class:PreSpawnGateError on the first failure.

#DevProcess

A supervised child process running in its own process group.

#start

python
def start(self) -> None

#pid

python
def pid(self) -> int | None

#is_running

python
def is_running(self) -> bool

#returncode

python
def returncode(self) -> int | None

#forward_signal

python
def forward_signal(self, sig: int) -> None

Forward sig to the child's process group (if still running).

#stop

python
def stop(self, grace_s: float | None=None) -> None

Graceful-then-kill: SIGTERM the group, wait grace_s, then SIGKILL.

#teardown

python
def teardown(components: list[DevProcess], grace_s: float=GRACE_DEFAULT) -> None

Stop components in reverse start order.

#supervise_loop

python
def supervise_loop(started: list[DevProcess], stop_flag: dict, poll_s: float=0.2) -> DevProcess | None

Block until a component dies or stop_flag['flag'] is set.

Returns the first dead :class:DevProcess, or None when a stop was requested (clean shutdown). Does not tear anything down -- the caller owns teardown so ordering stays in one place.

#_serve_in_process

python
def _serve_in_process(app_path: str, host: str, port: int, vite_port: int) -> None

Subprocess entry point: import an app, wrap with ViteDevProxy, serve it.

#_start_ordered

python
def _start_ordered(cfg: DevConfig, grace_s: float, started: list[DevProcess]) -> None

Start vite + backend in the order dictated by topology, readying each.

#resolve_backend_sw_mode

python
def resolve_backend_sw_mode(cfg: DevConfig) -> str | None

Import the in-process app and return its resolved sw_mode (or None).

Only meaningful for the app backend form; returns None for cmd-form backends (whose sw_mode cannot be introspected without running them).

#check_sw_mode

python
def check_sw_mode(cfg: DevConfig) -> None

Hard-error if the resolved in-process app uses sw_mode='cache'.

cmd-form backends run as opaque subprocesses whose sw_mode cannot be introspected without executing them, so the guard cannot verify them. Rather than skip silently, emit a one-line stderr notice so the operator knows the guard did not run for this backend.

#dev_pid_path

python
def dev_pid_path(cfg: DevConfig, pid_dir: Path | str | None=None) -> Path

#list_dev_instances

python
def list_dev_instances(cfg: DevConfig, pid_dir: Path | str | None=None)

Return live registered dev instances (registry entries with the dev role).

#stop_dev_instances

python
def stop_dev_instances(cfg: DevConfig, pid_dir: Path | str | None=None, grace_s: float=GRACE_DEFAULT)

Terminate every registered dev instance gracefully-then-kill. Returns them.

#_spawn_daemon

python
def _spawn_daemon(cfg: DevConfig, pid_dir: Path | str | None) -> int

Spawn a detached fastware dev run --no-daemon and wait for it to register.

#run_dev

python
def run_dev(cfg: DevConfig, *, daemon: bool, grace_s: float=GRACE_DEFAULT, pid_dir: Path | str | None=None) -> int

Run the dev environment. Foreground blocks; daemon detaches and returns.

Always performs the sw_mode='cache' hard-error check up front.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search