pharos_native/runtime/

ops_bridge.rs

//! Native operational helpers migrated from the runtime ops and helper surfaces.
//!
//! The functions are deliberately data- and filesystem-only. They do not spawn
//! shell commands, interpolate untrusted SQL, or write outside caller-selected roots.

use serde_json::Value;
use std::path::{Path, PathBuf};

use crate::config::ServeConfig;

/// Appends the shared app flags to an owned argv vector in stable order.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::runtime::ops_bridge::append_app_common_flags`].
/// - `argv`: Input consumed by [`crate::runtime::ops_bridge::append_app_common_flags`].
///
/// # Returns
///
/// Returns after [`crate::runtime::ops_bridge::append_app_common_flags`] applies its in-place effect.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::append_app_common_flags`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::append_app_common_flags(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn append_app_common_flags(config: &ServeConfig, argv: &mut Vec<String>) {
    let flags = [
        ("--conf", config.conf_path.as_deref()),
        ("--app-dir", config.app_dir.as_deref()),
        ("--build-dir", config.build_dir.as_deref()),
        ("--state-dir", config.state_dir.as_deref()),
        ("--state-path", config.state_path.as_deref()),
        ("--base-path", config.base_path.as_deref()),
    ];
    for (flag, value) in flags {
        if let Some(value) = value.filter(|value| !value.is_empty()) {
            argv.push(flag.to_owned());
            argv.push(value.to_owned());
        }
    }
}

/// Fails closed for the retired shell runtime bridge; Rust dispatch owns behavior directly.
///
/// # Parameters
///
/// - `_repo_root`: Input consumed by [`crate::runtime::ops_bridge::runtime_script_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ops_bridge::runtime_script_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::runtime_script_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn runtime_script_path(_repo_root: &Path) -> Option<PathBuf> {
    None
}

/// Fails closed for the retired shell runtime bridge; Rust dispatch owns behavior directly.
///
/// # Parameters
///
/// - `_repo_root`: Input consumed by [`crate::runtime::ops_bridge::shell_runtime_command_capture`].
/// - `_args`: Input consumed by [`crate::runtime::ops_bridge::shell_runtime_command_capture`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::shell_runtime_command_capture`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::shell_runtime_command_capture`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::shell_runtime_command_capture(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn shell_runtime_command_capture(_repo_root: &Path, _args: &[String]) -> Result<String, i32> {
    Err(78)
}

/// Appends one owned argument while enforcing a fixed command-vector bound.
///
/// # Parameters
///
/// - `argv`: Input consumed by [`crate::runtime::ops_bridge::push_argv_value`].
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::push_argv_value`].
/// - `capacity`: Input consumed by [`crate::runtime::ops_bridge::push_argv_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::push_argv_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::push_argv_value(todo!(), "value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn push_argv_value(argv: &mut Vec<String>, value: Option<&str>, capacity: usize) -> i32 {
    pharos_runtime_ops::push_argv_value(argv, value, capacity)
}

/// Removes a temporary request body and clears its ownership slot.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::cleanup_temp_body_file`].
///
/// # Returns
///
/// Returns after [`crate::runtime::ops_bridge::cleanup_temp_body_file`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::cleanup_temp_body_file(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn cleanup_temp_body_file(path: &mut Option<PathBuf>) {
    pharos_runtime_ops::cleanup_temp_body_file(path)
}

/// Writes a bounded request body to a uniquely-created temporary file.
///
/// # Parameters
///
/// - `body`: Input consumed by [`crate::runtime::ops_bridge::write_temp_body_file`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::write_temp_body_file`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::write_temp_body_file`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::write_temp_body_file(b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn write_temp_body_file(body: Option<&[u8]>) -> Result<PathBuf, i32> {
    pharos_runtime_ops::write_temp_body_file(body)
}

/// Returns whether text is safe for an identifier position.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::ops_bridge::identifier_safe`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::identifier_safe`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::identifier_safe`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::identifier_safe("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn identifier_safe(text: &str) -> bool {
    pharos_runtime_ops::identifier_safe(text)
}

/// Escapes a value for a SQL string literal without constructing a query.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::ops_bridge::sql_literal_escape`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::sql_literal_escape`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::sql_literal_escape("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn sql_literal_escape(text: &str) -> String {
    pharos_runtime_ops::sql_literal_escape(text)
}

/// Trims a captured command-like value while rejecting control characters.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::ops_bridge::capture_trimmed`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ops_bridge::capture_trimmed`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::capture_trimmed`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::capture_trimmed("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn capture_trimmed(text: &str) -> Option<String> {
    pharos_runtime_ops::capture_trimmed(text)
}

/// Returns whether a deployment packaging directory is present and usable.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::ops_bridge::cross_deb_packaging_available`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::cross_deb_packaging_available`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::cross_deb_packaging_available(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn cross_deb_packaging_available(root: &Path) -> bool {
    pharos_runtime_ops::cross_deb_packaging_available(root)
}

/// Checks whether an executable is available on PATH without invoking it.
///
/// # Parameters
///
/// - `command`: Input consumed by [`crate::runtime::ops_bridge::command_exists`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::command_exists`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::command_exists(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn command_exists(command: &str) -> bool {
    pharos_runtime_ops::command_exists(command)
}

/// Appends one bounded access-log line to a runtime-owned log file.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
/// - `app_id`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
/// - `method`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
/// - `request_path`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
/// - `status_text`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
/// - `reason`: Input consumed by [`crate::runtime::ops_bridge::write_error_log`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::write_error_log`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::write_error_log`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::write_error_log(std::path::Path::new("fixture.json"), todo!(), todo!(), "/", "400 Bad Request", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn write_error_log(
    path: &Path,
    app_id: Option<&str>,
    method: Option<&str>,
    request_path: Option<&str>,
    status_text: Option<&str>,
    reason: Option<&str>,
) -> i32 {
    pharos_runtime_ops::write_error_log(path, app_id, method, request_path, status_text, reason)
}

/// Writes access log.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::write_access_log`].
/// - `line`: Input consumed by [`crate::runtime::ops_bridge::write_access_log`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::write_access_log`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::write_access_log`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::write_access_log(std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn write_access_log(path: &Path, line: &str) -> i32 {
    pharos_runtime_ops::write_access_log(path, line)
}

/// Resolves the configured HTTP body limit with a bounded default.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::http_body_limit`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::http_body_limit`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::http_body_limit("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn http_body_limit(value: Option<i64>) -> usize {
    pharos_runtime_ops::http_body_limit(value)
}

/// Spools a bounded request body to a caller-selected temporary path.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::spool_request_body_to_temp_file`].
/// - `body`: Input consumed by [`crate::runtime::ops_bridge::spool_request_body_to_temp_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::spool_request_body_to_temp_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::spool_request_body_to_temp_file(std::path::Path::new("fixture.json"), b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn spool_request_body_to_temp_file(path: &Path, body: &[u8]) -> i32 {
    pharos_runtime_ops::spool_request_body_to_temp_file(path, body)
}

/// Appends an escaped key/value pair to PostgreSQL conninfo text.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append_kv`].
/// - `key`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append_kv`].
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append_kv`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::conninfo_append_kv`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::conninfo_append_kv(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn conninfo_append_kv(output: &mut String, key: &str, value: &str) -> bool {
    pharos_runtime_ops::conninfo_append(output, key, value)
}

/// Returns whether a configured PostgreSQL adapter handle candidate is usable.
///
/// # Parameters
///
/// - `candidate`: Input consumed by [`crate::runtime::ops_bridge::open_libpq_handle_candidate`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::open_libpq_handle_candidate`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::open_libpq_handle_candidate(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn open_libpq_handle_candidate(candidate: Option<&Path>) -> bool {
    pharos_runtime_ops::open_libpq_handle_candidate(candidate)
}

/// Converts a JSON scalar into a bounded signed integer.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::long_from_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::long_from_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::long_from_value("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn long_from_value(value: &Value) -> i64 {
    pharos_runtime_ops::long_from_value(value)
}

/// Reports whether a SQLite database path is readable and regular.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::db_check_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::db_check_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::db_check_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::db_check_json(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn db_check_json(path: &Path) -> Result<String, &'static str> {
    pharos_runtime_ops::db_check_json(path)
}

/// Resolves an explicitly configured database backend.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ops_bridge::default_backend`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::ops_bridge::default_backend`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ops_bridge::default_backend`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::default_backend(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn default_backend(app_root: &Path, runtime_conf_path: Option<&Path>) -> Option<String> {
    super::database::dynamic_relational_backend(app_root, runtime_conf_path)
}

/// Returns a bounded JSON description of one output path.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::output_path_status`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::output_path_status`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::output_path_status`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::output_path_status(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn output_path_status(path: &Path) -> Result<String, i32> {
    pharos_runtime_ops::output_path_status(path)
}

/// Returns the default native execution environment.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ops_bridge::default_environment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::default_environment();
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn default_environment() -> &'static str {
    pharos_runtime_ops::default_environment()
}

/// Validates a supported runtime environment name.
///
/// # Parameters
///
/// - `environment`: Input consumed by [`crate::runtime::ops_bridge::environment_valid`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::environment_valid`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::environment_valid(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn environment_valid(environment: &str) -> bool {
    pharos_runtime_ops::environment_valid(environment)
}

/// Checks one output path and returns its bounded JSON disposition.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::ops_bridge::output_path_check_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::output_path_check_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::output_path_check_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::output_path_check_json(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn output_path_check_json(path: &Path) -> Result<String, &'static str> {
    pharos_runtime_ops::output_path_check_json(path)
}

/// Appends one SQL-literal character with the escaping required by SQLite and PostgreSQL.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::ops_bridge::append_escaped_sql_char`].
/// - `character`: Input consumed by [`crate::runtime::ops_bridge::append_escaped_sql_char`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::append_escaped_sql_char`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::append_escaped_sql_char(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn append_escaped_sql_char(output: &mut String, character: char) -> bool {
    pharos_runtime_ops::append_escaped_sql_char(output, character)
}

/// Writes macOS-compatible no-index markers to a directory tree.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::ops_bridge::write_noindex_markers_recursive`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::write_noindex_markers_recursive`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::write_noindex_markers_recursive`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::write_noindex_markers_recursive(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn write_noindex_markers_recursive(root: &Path) -> Result<usize, &'static str> {
    pharos_runtime_ops::write_noindex_markers_recursive(root)
}

/// Matches the native operational command tuple exactly enough for dispatch.
///
/// # Parameters
///
/// - `args`: Input consumed by [`crate::runtime::ops_bridge::match_ops_command`].
/// - `first`: Input consumed by [`crate::runtime::ops_bridge::match_ops_command`].
/// - `second`: Input consumed by [`crate::runtime::ops_bridge::match_ops_command`].
/// - `third`: Input consumed by [`crate::runtime::ops_bridge::match_ops_command`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::match_ops_command`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::match_ops_command(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn match_ops_command(args: &[String], first: &str, second: &str, third: Option<&str>) -> bool {
    pharos_runtime_ops::match_ops_command(args, first, second, third)
}

/// Normalizes an app-relative base path without allowing traversal.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::normalize_base_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ops_bridge::normalize_base_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::normalize_base_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::normalize_base_path("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn normalize_base_path(value: &str) -> Option<String> {
    pharos_runtime_ops::normalize_base_path(value)
}

/// Returns a path under a trusted root for a validated relative helper value.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::ops_bridge::resolve_runtime_path`].
/// - `relative`: Input consumed by [`crate::runtime::ops_bridge::resolve_runtime_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ops_bridge::resolve_runtime_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::resolve_runtime_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::resolve_runtime_path(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn resolve_runtime_path(root: &Path, relative: &str) -> Option<PathBuf> {
    pharos_runtime_ops::resolve_runtime_path(root, relative)
}

/// Builds a bounded deployment-check report from declarative metadata.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ops_bridge::build_app_deploy_check_report_local_json`].
/// - `target_id`: Input consumed by [`crate::runtime::ops_bridge::build_app_deploy_check_report_local_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::build_app_deploy_check_report_local_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::build_app_deploy_check_report_local_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::build_app_deploy_check_report_local_json(std::path::Path::new("apps/dev_docs"), "dev_docs");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn build_app_deploy_check_report_local_json(
    app_root: &Path,
    target_id: &str,
) -> Result<String, &'static str> {
    pharos_runtime_ops::build_app_deploy_check_report_local_json(app_root, target_id)
}

/// Builds a bounded drift report from two JSON documents.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ops_bridge::build_app_doctor_report_local_json`].
/// - `target_id`: Input consumed by [`crate::runtime::ops_bridge::build_app_doctor_report_local_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::build_app_doctor_report_local_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::build_app_doctor_report_local_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::build_app_doctor_report_local_json(std::path::Path::new("apps/dev_docs"), "dev_docs");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn build_app_doctor_report_local_json(
    app_root: &Path,
    target_id: &str,
) -> Result<String, &'static str> {
    pharos_runtime_ops::build_app_doctor_report_local_json(app_root, target_id)
}

/// Builds app drift report local JSON.
///
/// # Parameters
///
/// - `expected_path`: Input consumed by [`crate::runtime::ops_bridge::build_app_drift_report_local_json`].
/// - `actual_path`: Input consumed by [`crate::runtime::ops_bridge::build_app_drift_report_local_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::ops_bridge::build_app_drift_report_local_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::ops_bridge::build_app_drift_report_local_json`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ops_bridge::build_app_drift_report_local_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::build_app_drift_report_local_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn build_app_drift_report_local_json(
    expected_path: &Path,
    actual_path: &Path,
) -> Result<String, &'static str> {
    pharos_runtime_ops::build_app_drift_report_local_json(expected_path, actual_path)
}

/// Appends one validated key/value pair to PostgreSQL connection information.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append`].
/// - `key`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append`].
/// - `value`: Input consumed by [`crate::runtime::ops_bridge::conninfo_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ops_bridge::conninfo_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ops_bridge::conninfo_append(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ops_bridge`] for adjacent helpers that share the same runtime surface.
pub fn conninfo_append(output: &mut String, key: &str, value: &str) -> bool {
    conninfo_append_kv(output, key, value)
}