@spec cleanup_runtime_process(port(), term()) :: term()

Safely terminates a runtime process with proper cleanup.

@spec format_error(term()) :: String.t()

Formats error messages consistently across runtimes.

@spec get_port_os_pid(port()) :: integer() | nil

Gets OS PID from port with error handling.

@spec handle_file_change(String.t(), module(), keyword(), timeout()) ::
  :ok | {:error, term()}

Handles file change events with async processing and timeout. Uses non-blocking approach to prevent GenServer blocking.

@spec handle_result(term()) :: {:ok, term()} | {:error, String.t()}

Standardized error handling for runtime operations.

Returns {:ok, result} or {:error, reason} tuples consistently.

Makes HTTP request to runtime server with standardized error handling.

@spec merge_config(keyword(), keyword(), atom()) ::
  {:ok, keyword()} | {:error, String.t()}

Merges user configuration with defaults, applying validation.

@spec normalize_exit_reason(term()) :: term()

Normalizes exit reasons for consistent process termination.

@spec port_options(String.t(), [String.t()], keyword()) :: keyword()

Creates port options for spawning runtime processes.

@spec runtime_env(String.t(), String.t(), String.t(), String.t()) :: [
  {charlist(), charlist()}
]

Creates environment variables for runtime processes.

@spec validate_config(
  keyword(),
  atom()
) :: {:ok, keyword()} | {:error, String.t()}

Validates configuration values with proper error messages.