v0.1.4-pre.012

crates/ksp-app-config-desk/src/environment.rs

@@ -1,7 +1,7 @@
 // file: crates/ksp-app-config-desk/src/environment.rs
-// version: 1
+// version: 2
 
-//! Safe Config environment report projections for Config Desk.
+//! Safe Config environment reports and `.env` management projections for Config Desk.
 
 use ts_rs::TS; // rust-rules: derive-import
 
@@ -26,11 +26,57 @@ pub(crate) struct ConfigEnvironmentReportDto {
     pub(crate) shadowed_by_process_environment: bool,
 }
 
+/// Safe result metadata for one `.env` mutation.
+#[derive(Clone, Debug, serde::Serialize, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export, export_to = "../frontend/ts/bindings/ksp_app_config_desk/environment/ConfigEnvironmentChangeDto.ts")]
+pub(crate) struct ConfigEnvironmentChangeDto {
+    /// Variable targeted by the operation; never its value.
+    pub(crate) variable_name: String,
+    /// Stable operation label: `set` or `remove`.
+    pub(crate) operation: String,
+    /// Sensitivity classified by Config from the variable namespace.
+    pub(crate) sensitivity: String,
+    /// Whether the persisted `.env` source bytes changed.
+    pub(crate) source_changed: bool,
+    /// Whether the effective process-or-`.env` value changed for the running process.
+    pub(crate) effective_changed: bool,
+    /// Whether the resulting `.env` entry is shadowed by inherited process environment.
+    pub(crate) shadowed_by_process_environment: bool,
+    /// Whether consumers holding an environment snapshot must reload to observe the effective change.
+    pub(crate) reload_required: bool,
+}
+
+#[derive(Clone, Copy)]
+enum EnvironmentMutationOperation {
+    Set,
+    Remove,
+}
+
+impl EnvironmentMutationOperation {
+    const fn label(self) -> &'static str {
+        return match self {
+            Self::Set => "set",
+            Self::Remove => "remove",
+        };
+    }
+}
+
 /// Returns the safe environment report owned by Config.
 pub(crate) fn report(state: &crate::AppState) -> ksp_core_lib::Result<std::vec::Vec<ConfigEnvironmentReportDto>> {
     return report_from_management(state.config_management());
 }
 
+/// Creates or replaces one `.env` entry exclusively through ConfigManagement.
+pub(crate) fn set_value(state: &crate::AppState, variable_name: &str, value: &str) -> ksp_core_lib::Result<ConfigEnvironmentChangeDto> {
+    return set_value_from_management(state.config_management(), variable_name, value);
+}
+
+/// Removes one `.env` entry exclusively through ConfigManagement.
+pub(crate) fn remove_value(state: &crate::AppState, variable_name: &str) -> ksp_core_lib::Result<ConfigEnvironmentChangeDto> {
+    return remove_value_from_management(state.config_management(), variable_name);
+}
+
 fn report_from_management(management: &ksp_config_lib::ConfigManagement) -> ksp_core_lib::Result<std::vec::Vec<ConfigEnvironmentReportDto>> {
     let reports = management.environment_report();
     let reports = match reports {
@@ -78,6 +124,72 @@ fn report_from_management(management: &ksp_config_lib::ConfigManagement) -> ksp_
     return std::result::Result::Ok(result);
 }
 
+fn set_value_from_management(
+    management: &ksp_config_lib::ConfigManagement,
+    variable_name: &str,
+    value: &str,
+) -> ksp_core_lib::Result<ConfigEnvironmentChangeDto> {
+    let sensitivity = mutation_sensitivity(variable_name);
+    let sensitivity = match sensitivity {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let report = management.set_dotenv_value(variable_name, value);
+    let report = match report {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    return std::result::Result::Ok(mutation_result(variable_name, EnvironmentMutationOperation::Set, sensitivity, report));
+}
+
+fn remove_value_from_management(management: &ksp_config_lib::ConfigManagement, variable_name: &str) -> ksp_core_lib::Result<ConfigEnvironmentChangeDto> {
+    let sensitivity = mutation_sensitivity(variable_name);
+    let sensitivity = match sensitivity {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let report = management.remove_dotenv_value(variable_name);
+    let report = match report {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    return std::result::Result::Ok(mutation_result(variable_name, EnvironmentMutationOperation::Remove, sensitivity, report));
+}
+
+fn mutation_result(
+    variable_name: &str,
+    operation: EnvironmentMutationOperation,
+    sensitivity: ksp_config_lib::ConfigSensitivity,
+    report: ksp_config_lib::ConfigEnvironmentChangeReport,
+) -> ConfigEnvironmentChangeDto {
+    let result = ConfigEnvironmentChangeDto {
+        variable_name: variable_name.to_owned(),
+        operation: operation.label().to_owned(),
+        sensitivity: sensitivity_label(sensitivity).to_owned(),
+        source_changed: report.source_changed(),
+        effective_changed: report.effective_changed(),
+        shadowed_by_process_environment: report.shadowed_by_process_environment(),
+        reload_required: report.reload_required(),
+    };
+    ksp_logging_lib::debug!(
+        target: crate::TRACING_TARGET,
+        domain = crate::TRACING_DOMAIN_ENVIRONMENT,
+        variable_name = result.variable_name.as_str(),
+        operation = result.operation.as_str(),
+        sensitivity = result.sensitivity.as_str(),
+        source_changed = result.source_changed,
+        effective_changed = result.effective_changed,
+        shadowed_by_process_environment = result.shadowed_by_process_environment,
+        reload_required = result.reload_required,
+        "Config .env mutation completed"
+    );
+    return result;
+}
+
+fn mutation_sensitivity(variable_name: &str) -> ksp_core_lib::Result<ksp_config_lib::ConfigSensitivity> {
+    return ksp_config_lib::ConfigSensitivity::from_variable_name(variable_name);
+}
+
 const fn environment_source_label(source: std::option::Option<ksp_config_lib::ConfigEnvironmentSource>) -> &'static str {
     return match source {
         std::option::Option::Some(ksp_config_lib::ConfigEnvironmentSource::Process) => "process",