0.5.1-pre.002

ks-config/src/environment.rs

@@ -0,0 +1,95 @@
+// file: ks-config/src/environment.rs
+// version: 4
+
+//! Environment-file loading and configuration placeholder resolution.
+
+/// Result of loading one optional workspace environment file.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct EnvironmentLoadReport {
+    /// Explicit or default environment file that was loaded.
+    pub loaded_path: std::option::Option<std::path::PathBuf>,
+}
+
+/// Loads the selected environment file without overriding process variables.
+///
+/// Resolution order is: existing process environment, selected `.env`, then
+/// fallback text declared with `${NAME:-fallback}` placeholders.
+pub fn load_workspace_environment(
+    workspace_root: &std::path::Path,
+) -> ks_core::Result<EnvironmentLoadReport> {
+    let explicit_path = std::env::var("KB_ENV_FILE").ok();
+    let selected_path = match explicit_path {
+        std::option::Option::Some(path) if !path.trim().is_empty() => {
+            let candidate = std::path::PathBuf::from(path);
+            if candidate.is_absolute() { candidate } else { workspace_root.join(candidate) }
+        },
+        _ => workspace_root.join(".env"),
+    };
+    if !selected_path.exists() {
+        return std::result::Result::Ok(EnvironmentLoadReport { loaded_path: None });
+    }
+    return match dotenvy::from_path(&selected_path) {
+        std::result::Result::Ok(()) => std::result::Result::Ok(EnvironmentLoadReport {
+            loaded_path: std::option::Option::Some(selected_path),
+        }),
+        std::result::Result::Err(error) => std::result::Result::Err(ks_core::Error::new(
+            "config_env_file_load_failed",
+            format!("{}: {error}", selected_path.display()),
+        )),
+    };
+}
+
+/// Resolves `${NAME}` and `${NAME:-fallback}` placeholders in arbitrary text.
+/// Missing variables without fallbacks are preserved for lazy consumers.
+pub fn resolve_environment_placeholders(raw: &str) -> std::string::String {
+    let mut output = std::string::String::with_capacity(raw.len());
+    let bytes = raw.as_bytes();
+    let mut index = 0_usize;
+    while index < bytes.len() {
+        if bytes[index] == b'$' && index + 1 < bytes.len() && bytes[index + 1] == b'{' {
+            let start = index;
+            let mut end = index + 2;
+            while end < bytes.len() && bytes[end] != b'}' {
+                end += 1;
+            }
+            if end < bytes.len() {
+                let expression = &raw[index + 2..end];
+                let (name, fallback) = match expression.split_once(":-") {
+                    std::option::Option::Some((name, fallback)) => {
+                        (name, std::option::Option::Some(fallback))
+                    },
+                    std::option::Option::None => (expression, std::option::Option::None),
+                };
+                let resolved = std::env::var(name)
+                    .ok()
+                    .or_else(|| return fallback.map(|value| return value.to_string()));
+                match resolved {
+                    std::option::Option::Some(value) => output.push_str(&value),
+                    std::option::Option::None => output.push_str(&raw[start..=end]),
+                }
+                index = end + 1;
+                continue;
+            }
+        }
+        output.push(bytes[index] as char);
+        index += 1;
+    }
+    return output;
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn fallback_is_used_when_variable_is_absent() {
+        let resolved =
+            super::resolve_environment_placeholders("${KB_CONFIG_TEST_MISSING:-fallback}");
+        assert_eq!(resolved, "fallback");
+    }
+
+    #[test]
+    fn unresolved_required_placeholder_is_preserved() {
+        let resolved =
+            super::resolve_environment_placeholders("prefix-${KB_CONFIG_TEST_MISSING}-suffix");
+        assert_eq!(resolved, "prefix-${KB_CONFIG_TEST_MISSING}-suffix");
+    }
+}

ks-config/src/lib.rs

@@ -0,0 +1,79 @@
+// file: ks-config/src/lib.rs
+// version: 5
+
+//! Khadhroony Bot3 workspace configuration contract and loading helpers.
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+mod environment;
+mod settings;
+
+/// Exposes the environment loading report.
+pub use self::environment::EnvironmentLoadReport;
+/// Exposes workspace environment-file loading.
+pub use self::environment::load_workspace_environment;
+/// Exposes environment placeholder resolution.
+pub use self::environment::resolve_environment_placeholders;
+/// Exposes the account listener configuration type.
+pub use self::settings::AccountListenerConfig;
+/// Exposes the root application configuration type.
+pub use self::settings::AppConfig;
+/// Exposes the application section configuration type.
+pub use self::settings::AppSectionConfig;
+/// Exposes the local data configuration type.
+pub use self::settings::DataConfig;
+/// Exposes the database configuration type.
+pub use self::settings::DatabaseConfig;
+/// Exposes the demo application configuration type.
+pub use self::settings::DemoConfig;
+/// Exposes the endpoint role configuration type.
+pub use self::settings::EndpointRoleConfig;
+/// Exposes the execution configuration type.
+pub use self::settings::ExecutionConfig;
+/// Exposes the HTTP endpoint configuration type.
+pub use self::settings::HttpEndpointConfig;
+/// Exposes the listener configuration type.
+pub use self::settings::ListenerConfig;
+/// Exposes the log listener configuration type.
+pub use self::settings::LogListenerConfig;
+/// Exposes the logging target configuration type.
+pub use self::settings::LogTargetConfig;
+/// Exposes the logging target filter configuration type.
+pub use self::settings::LogTargetFilterConfig;
+/// Exposes the logging configuration type.
+pub use self::settings::LoggingConfig;
+/// Exposes the PostgreSQL configuration type.
+pub use self::settings::PostgresConfig;
+/// Exposes the profile configuration type.
+pub use self::settings::ProfileConfig;
+/// Exposes the program listener configuration type.
+pub use self::settings::ProgramListenerConfig;
+/// Exposes the Solana configuration type.
+pub use self::settings::SolanaConfig;
+/// Exposes the SQLite configuration type.
+pub use self::settings::SqliteConfig;
+/// Exposes the wallet configuration type.
+pub use self::settings::WalletConfig;
+/// Exposes the WebSocket endpoint configuration type.
+pub use self::settings::WsEndpointConfig;
+/// Exposes the active profile resolver.
+pub use self::settings::active_profile;
+/// Exposes the embedded JSON Schema text.
+pub use self::settings::config_json_schema_text;
+/// Exposes the embedded JSON Schema value parser.
+pub use self::settings::config_json_schema_value;
+/// Exposes the configuration parser from a JSON string.
+pub use self::settings::parse_config_json;
+/// Exposes the configuration loader from a filesystem path.
+pub use self::settings::read_config_json_file;
+/// Exposes configuration loading with workspace environment resolution.
+pub use self::settings::read_config_json_file_with_environment;
+/// Exposes the compact JSON serializer for configuration values.
+pub use self::settings::serialize_config_json;
+/// Exposes the pretty JSON serializer for configuration values.
+pub use self::settings::serialize_config_json_pretty;
+/// Exposes the typed configuration validator.
+pub use self::settings::validate_config;
+/// Exposes the JSON Schema validator for raw JSON configuration.
+pub use self::settings::validate_config_json_schema;