Runtime & Environment

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_cli/_utilities/runtime.py
• src/flext_cli/_utilities/processes.py
• AGENTS.md
• pyproject.toml
• examples/ex_01_getting_started.py
• src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_06.py

The Runtime & Environment module provides the infrastructure for executing external processes, managing environment variables, and handling the application's runtime state. It serves as the bridge between the Python application and the host operating system, ensuring that command execution is consistent, typed, and integrated into the project's error-handling patterns.

The system is built around the FlextCliUtilitiesRuntime class, which wraps standard library process management with additional layers for environment resolution, timeout handling, and output capturing. It strictly adheres to the project's "Railway" pattern using p.Result for all fallible operations.
Sources: src/flext_cli/_utilities/runtime.py:15-17, examples/ex_01_getting_started.py:46-52

Process Execution Architecture

The core logic for process execution is encapsulated in run_raw and run. These methods manage the lifecycle of a subprocess, including environment setup, input/output piping, and execution timing.

Execution Flow

The following diagram illustrates how a command is prepared, executed, and converted into a typed result:

The system captures stdout, stderr, and exit_code, while also calculating the precise duration of the execution using time.monotonic().
Sources: src/flext_cli/_utilities/runtime.py:44-84

Core Execution Methods

Method	Purpose	Failure Condition
run_raw	Executes a command and returns output regardless of exit code.	Timeout or OS execution error.
run	Executes a command and enforces a zero exit code.	Non-zero exit code, Timeout, or OS error.
run_checked	Returns a boolean success flag based on execution result.	Same as run.
capture	Returns the stripped stdout of a successful command.	Same as run.
run_to_file	Redirects combined stdout/stderr to a specified file.	Timeout or OS error.

Sources: src/flext_cli/_utilities/runtime.py:44-149

Environment Management

Environment variables are managed through a resolution process that combines inherited system environments with specific overrides and exclusion keys.

The process_env method utilizes a m.Cli.ProcessEnvironmentSpec model to validate and merge these components. This ensures that child processes have a strictly controlled environment, preventing credential leakage or configuration contamination.
Sources: src/flext_cli/_utilities/runtime.py:20-42

Integration with External Tools

The runtime utilities are frequently used to wrap external CLI tools such as taplo for formatting TOML files. This integration demonstrates the use of run_raw with specific working directories and environment resolution.

command = ["taplo", "format"]
config_path = self._resolve_taplo_config(path)
if config_path is not None:
    command.extend(["--config", str(config_path)])
command.append(str(path))

return (
    ur.run_raw(command, cwd=path.parent)
    .flat_map(lambda output: (
        r[bool].ok(True) if output.exit_code == 0 
        else r[bool].fail(output.stderr or "taplo failed")
    ))
)

Sources: src/flext_cli/_utilities/_toml_parts/flextcliutilitiestoml_part_06.py:73-98

Global Engineering Principles

The Runtime & Environment system is governed by several critical engineering laws defined in the project's core documentation:

1. Truth with Evidence: Execution results must include exact command details, exit status, and decisive output.
2. Continuous Green: The environment must not remain broken or partially migrated. Gates (Ruff, Pytest, MyPy) are enforced with the same rigor for examples as for production code.
3. P0 - Tests Validate Config: Tests and examples must never hardcode configuration values; they must read from the single source of truth (SSOT) defined in settings.
4. Fixed Forward: If a runtime conflict occurs, the system must "fix forward" rather than reverting to maintain the integrity of shared worktrees.

Sources: AGENTS.md:18-45, AGENTS.md:173-181

Project Runtime Requirements

The project environment is strictly defined in the configuration metadata, ensuring compatibility across different developer machines:

• Python Version: Requires Python >=3.13 and <3.14.
• Dependencies: Relies on pydantic-settings for environment-driven configuration and psutil for process management.
• Platform: Designated as platform class project, intended to be OS-independent.

Sources: pyproject.toml:25-45, README.md:5-10

Conclusion

The Runtime & Environment module provides a robust, typed interface for system-level operations. By wrapping standard execution in a railway-oriented result pattern and enforcing strict environment resolution, it ensures that flext-cli applications remain stable and predictable across diverse execution contexts.