v0.1.4-pre.001-fix.002

deltas/0.1.4/pre.001-fix.002.md

@@ -0,0 +1,210 @@
+<!-- file: deltas/0.1.4/pre.001-fix.002.md -->
+<!-- version: 1 -->
+
+# Delta 0.1.4-pre.001-fix.002 — panneau `.env` et validation complète de l'environnement Config
+
+## Base requise
+
+```text
+0.1.4-pre.001-fix.001
+workspace.package.version = "0.1.4-pre.1"
+```
+
+Ce second correctif reste exclusivement documentaire. Il complète le plan de `pre.001` avant son approbation définitive et n'ouvre pas `pre.002`.
+
+Les deltas historiques :
+
+```text
+deltas/0.1.4/pre.001.md
+deltas/0.1.4/pre.001-fix.001.md
+```
+
+restent inchangés. Le présent fix porte uniquement la correction supplémentaire demandée après validation partielle du plan.
+
+## Objet
+
+`ksp-app-config-desk` doit servir de banc de validation réel de `ksp-config-lib`. Le plan couvrait déjà les rapports d'environnement et les mutations `.env`, mais ne les formulait pas encore comme un **panneau fonctionnel de test/management `.env`** avec une matrice de validation explicite.
+
+Le correctif rend donc obligatoire un panneau `Environnement / .env` capable de démontrer depuis l'UI :
+
+- les rapports `desired` / `effective` / source / shadowing ;
+- la classification `Public` / `Internal` / `Secret` et les safe values ;
+- la création et la modification d'une entrée `.env` via `ConfigManagement::set_dotenv_value()` ;
+- la suppression via `ConfigManagement::remove_dotenv_value()` ;
+- le retour `source_changed` / `effective_changed` / `shadowed_by_process_environment` / `reload_required` ;
+- le rechargement d'un rapport frais après mutation ;
+- la priorité `process > .env > fallback` avec un cas de shadowing observable ;
+- l'impossibilité pour l'application de modifier l'environnement déjà hérité du processus parent ;
+- la propagation d'une mutation `.env` vers une nouvelle résolution Config dépendante d'un placeholder ;
+- les frontières de reveal Secret déjà prévues, sans préchargement automatique d'une ancienne valeur Secret réelle dans l'éditeur.
+
+Aucun accès direct au fichier `.env` n'est ajouté à l'application.
+
+## Cas de validation Config existant
+
+Le plan utilise un cas déjà présent dans la base stable, sans inventer de nouveau document Config :
+
+```text
+config/std.logging.json
+logs_directory = "${KSP_LOGS_DIRECTORY:-logs}"
+```
+
+Le panneau doit permettre de modifier `KSP_LOGS_DIRECTORY` via Config puis de demander une nouvelle résolution du document/profil Logging.
+
+Deux résultats doivent être démontrables :
+
+1. sans valeur process prioritaire, la nouvelle valeur `.env` devient effective et la provenance/résolution change ;
+2. avec une valeur process prioritaire, la valeur `.env` désirée change mais la résolution effective reste celle du process et l'UI signale le shadowing. Ce second cas est reproductible en lançant l'application avec `KSP_LOGS_DIRECTORY=<valeur-process>`, puis en modifiant la même variable dans `.env` depuis l'UI.
+
+Le frontend ne résout jamais `${KSP_LOGS_DIRECTORY:-logs}` lui-même : l'autorité reste `ksp-config-lib`.
+
+## UX du panneau `.env`
+
+Le panneau est composé d'au moins :
+
+```text
+Rapport
+  - variable
+  - sensibilité
+  - desired_safe_value
+  - effective_safe_value
+  - source effective
+  - shadowed
+
+Éditeur/test
+  - variable existante ou nouveau nom KSP_*/KSPB_*
+  - nouvelle valeur
+  - Créer/Modifier
+  - Supprimer
+  - Recharger
+
+Résultat de mutation
+  - source_changed
+  - effective_changed
+  - shadowed_by_process_environment
+  - reload_required
+```
+
+Pour un `Secret` :
+
+- le champ de saisie est traité comme sensible ;
+- l'ancienne valeur réelle n'est pas chargée automatiquement ;
+- une nouvelle valeur peut être saisie explicitement pour remplacement ;
+- la consultation d'une valeur existante utilise uniquement la commande/DTO privilégié de reveal ;
+- aucune valeur réelle ne rejoint logs, diagnostics, snapshot ou état persistant.
+
+## Frontière Tauri/Config
+
+Le flux reste :
+
+```text
+UI
+ -> commande Tauri centralisée dans tauri.rs
+ -> environment_service
+ -> ConfigManagement
+ -> set_dotenv_value/remove_dotenv_value/environment_report
+```
+
+La crate applicative ne :
+
+- lit pas `.env` avec `std::fs` ;
+- n'écrit pas `.env` avec `std::fs` ;
+- ne parse pas le format dotenv comme autorité ;
+- ne lit pas `std::env::var*` pour KSP/KSPB ;
+- ne simule pas elle-même la priorité process/`.env`/fallback.
+
+## Découpage souple mis à jour
+
+Le budget cible reste **environ 15–20 minutes de travail effectif par prerelease**. Pour éviter une tranche Environnement trop large, elle est scindée en deux :
+
+```text
+pre.011  Environnement — rapports
+         - desired/effective/source/shadow
+         - sensibilité + safe values
+         - table issue uniquement de Config
+         - refresh/reload
+
+pre.012  Environnement — management/test .env
+         - create/update
+         - remove
+         - résultat de mutation
+         - cas process > .env
+         - cas placeholder KSP_LOGS_DIRECTORY
+
+pre.013  Secrets privilégiés
+...
+pre.017  panneau Test Logging
+pre.018  robustesse/extensibilité/tests desktop
+pre.019  clôture candidate
+```
+
+`pre.019` n'est pas un numéro de clôture contractuel. Les tranches restent scindables, fusionnables ou réordonnables selon la durée réelle et les dépendances rencontrées.
+
+## Critères de clôture ajoutés
+
+La release ne pourra pas être fermée sans démonstration depuis `ksp-app-config-desk` de :
+
+- création d'une entrée `.env` ;
+- modification d'une entrée `.env` ;
+- suppression d'une entrée `.env` ;
+- rapport frais après chaque mutation ;
+- distinction desired/effective ;
+- source process ou `.env` ;
+- shadowing réel ;
+- comportement `source_changed` / `effective_changed` / `reload_required` ;
+- résolution Config affectée par `KSP_LOGS_DIRECTORY` lorsque la valeur n'est pas shadowée ;
+- absence de résolution frontend des placeholders ;
+- traitement sûr des variables `Secret`.
+
+Cette matrice complète la matrice Logging déjà renforcée par `pre.001-fix.001`.
+
+## Fichier modifié
+
+```text
+docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md
+```
+
+Le header du plan passe de `version: 2` à `version: 3`.
+
+## Fichier ajouté
+
+```text
+deltas/0.1.4/pre.001-fix.002.md
+```
+
+## Version Cargo
+
+Aucune modification de `Cargo.toml`.
+
+Le correctif est documentaire uniquement ; `workspace.package.version` reste :
+
+```text
+0.1.4-pre.1
+```
+
+L'identifiant de livraison est :
+
+```text
+0.1.4-pre.001-fix.002
+```
+
+## Validations du correctif
+
+À contrôler avant livraison :
+
+- header `file:` / `version:` des deux fichiers ;
+- plan en `version: 3` ;
+- absence de modification de `Cargo.toml` ;
+- absence de modification des deltas `pre.001` et `pre.001-fix.001` ;
+- présence explicite du panneau `Environnement / .env` ;
+- présence des quatre indicateurs du `ConfigEnvironmentChangeReport` ;
+- create/update/remove uniquement via `ConfigManagement` ;
+- cas de shadowing process > `.env` ;
+- cas de résolution `${KSP_LOGS_DIRECTORY:-logs}` ;
+- aucune lecture/écriture `.env` directe attribuée à l'application ;
+- découpage Environnement sur deux prereleases d'environ 15–20 minutes ;
+- critères de clôture `.env` explicites ;
+- équilibre des fences Markdown ;
+- archive limitée au plan modifié et au nouveau delta.
+
+Aucune commande Cargo n'est requise spécifiquement pour ce correctif documentaire. Les validations Cargo globales restent celles prévues au passage effectif vers les tranches de développement et à la clôture de la release.

docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Plan `0.1.4` — `ksp-app-config-desk`
 
@@ -454,7 +454,7 @@ Navigation minimum :
 Vue d'ensemble
 Documents
 Profils
-Environnement
+Environnement / .env
 Logging
 ```
 
@@ -468,6 +468,7 @@ Affiche uniquement des informations sûres :
 - profil Logging runtime actif ;
 - génération/revision de reload ;
 - présence de shadowing environnement ;
+- dernier résultat de mutation/test `.env` ;
 - dernier résultat de test Logging interactif.
 
 ### 7.2 Documents
@@ -501,29 +502,76 @@ L'UI doit montrer :
 
 L'inspection générique par `file_id` reste prévue dans le shell, mais `0.1.4` ne crée pas d'éditeur générique de tout schema inconnu.
 
-### 7.4 Environnement
+### 7.4 Environnement / `.env`
 
-Table sûre pour les variables présentes dans les rapports Config :
+Ce panneau est une **surface fonctionnelle de validation de `ksp-config-lib`**, pas un simple écran de diagnostic. Il doit permettre de vérifier le comportement réel de `ConfigEnvironment` et `ConfigManagement` sans lecture/écriture directe de `.env` depuis l'application.
+
+Il comporte deux zones complémentaires.
+
+#### 7.4.1 Rapport desired/effective
+
+La table est alimentée uniquement par `ConfigManagement::environment_report()` et expose les variables KSP/KSPB présentes dans le process ou `.env` :
 
 - nom ;
 - namespace KSP/KSPB ;
-- sensibilité ;
+- sensibilité `Public` / `Internal` / `Secret` ;
-- `safe_value` desired `.env` ;
+- `desired_safe_value` persistée dans `.env` ;
-- `safe_value` effective ;
+- `effective_safe_value` ;
-- source effective process/`.env` ;
+- source effective `process` / `.env` ;
-- indicateur shadowed ;
+- indicateur `shadowed_by_process_environment` ;
-- actions créer/modifier/supprimer `.env` ;
+- actions management adaptées à la ligne ;
-- action privilégiée « Révéler » séparée.
+- action privilégiée « Révéler » séparée pour les valeurs réelles.
 
-Après une mutation `.env`, l'UI affiche explicitement :
+Aucune valeur réelle Secret n'est nécessaire pour construire cette table.
+
+#### 7.4.2 Management/test `.env`
+
+Une zone d'édition dédiée permet de tester réellement les frontières déjà fournies par Config :
 
 ```text
-source modifiée ?
+Variable : variable existante | nouveau nom KSP_*/KSPB_*
-valeur effective modifiée ?
+Valeur   : champ d'édition, masqué lorsqu'il s'agit d'un Secret
-shadowed par process ?
+Actions  : Créer/Modifier | Supprimer | Recharger le rapport
+Résultat : source_changed | effective_changed | shadowed | reload_required
 ```
 
-Elle ne prétend jamais modifier l'environnement du parent/process déjà hérité.
+Règles :
+
+- création/modification uniquement via `ConfigManagement::set_dotenv_value()` ;
+- suppression uniquement via `ConfigManagement::remove_dotenv_value()` ;
+- le backend Config reste seul responsable de la validation du nom, de l'encodage `.env`, de la persistence atomique et du rechargement de ses snapshots ;
+- l'application ne lit pas le fichier `.env` brut et ne reconstruit pas son format ;
+- après chaque mutation, le rapport est rechargé depuis Config afin de montrer l'état réellement persisté/effectif ;
+- le résultat `ConfigEnvironmentChangeReport` est présenté explicitement à l'opérateur ;
+- une valeur process héritée n'est jamais modifiée par l'application.
+
+Après une mutation `.env`, l'UI doit donc pouvoir afficher sans ambiguïté :
+
+```text
+source_changed      = true|false
+effective_changed   = true|false
+shadowed_by_process = true|false
+reload_required     = true|false
+```
+
+Le scénario de shadowing est un test fonctionnel obligatoire. Si par exemple le process fournit une variable et `.env` contient une autre valeur pour le même nom, une modification de `.env` doit changer la valeur desired mais laisser la valeur effective issue du process inchangée. L'UI doit expliquer que la priorité reste :
+
+```text
+process > .env > fallback de placeholder
+```
+
+et qu'un processus enfant ne peut pas modifier l'environnement déjà hérité de son parent. Le scénario reproductible de validation pourra lancer l'application avec `KSP_LOGS_DIRECTORY=<valeur-process>` dans l'environnement du process, puis modifier la même variable dans `.env` depuis le panneau et vérifier que la valeur effective reste celle du process.
+
+Le panneau sert aussi à valider le lien entre `.env` et la résolution des documents Config. La base stable fournit déjà un cas reproductible :
+
+```text
+config/std.logging.json
+logs_directory = "${KSP_LOGS_DIRECTORY:-logs}"
+```
+
+Une modification de `KSP_LOGS_DIRECTORY` via le panneau doit pouvoir être suivie d'une nouvelle résolution Config/Logging et rendre observable la nouvelle valeur effective/provenance, **sans que le frontend résolve lui-même le placeholder**. Si une variable process masque `KSP_LOGS_DIRECTORY`, le test doit au contraire démontrer que la modification `.env` n'affecte pas la résolution effective tant que le process reste prioritaire.
+
+Pour une variable `Secret`, l'ancienne valeur réelle n'est pas préchargée automatiquement dans le formulaire. Une nouvelle valeur peut être saisie explicitement pour remplacement ; la consultation de l'ancienne valeur passe exclusivement par le flux reveal privilégié décrit plus loin.
 
 ### 7.5 Logging
 
@@ -607,8 +655,8 @@ Les noms ci-dessous sont les noms fonctionnels cibles ; ils pourront être norma
 | `save_config_source_candidate` | `config_service`                     | future API Config de réparation validée                                     |                                          non |
 | `inspect_profile`              | `config_service`                     | `load_resolved_profile` + résolution détaillée                              |                                          non |
 | `get_environment_report`       | `environment_service`                | `ConfigManagement::environment_report`                                      |                                          non |
-| `set_dotenv_value`             | `environment_service`                | `ConfigManagement::set_dotenv_value`                                        | entrée potentiellement Secret, jamais loggée |
+| `set_dotenv_value`             | `environment_service`                | `ConfigManagement::set_dotenv_value` + rapport frais                        | entrée potentiellement Secret, jamais loggée |
-| `remove_dotenv_value`          | `environment_service`                | `ConfigManagement::remove_dotenv_value`                                     |                                          non |
+| `remove_dotenv_value`          | `environment_service`                | `ConfigManagement::remove_dotenv_value` + rapport frais                     |                                          non |
 | `reveal_environment_value`     | `secret_service`                     | `reveal_effective_environment_value` ou `reveal_dotenv_value`               |                                      **oui** |
 | `get_logging_editor`           | `logging_service`                    | `load_logging_document`                                                     |                                          non |
 | `save_logging_document`        | `logging_service`                    | `save_logging_document`                                                     |                       non par design Logging |
@@ -637,6 +685,7 @@ ConfigDocumentInspectionDto
 ConfigDiagnosticDto
 ProfileInspectionDto
 EnvironmentVariableReportDto
+DotenvMutationRequestDto
 EnvironmentMutationResultDto
 LoggingDocumentDto
 LoggingProfileDto
@@ -932,6 +981,9 @@ Tests ciblés :
 - conversion sûre `ksp_core_lib::Error` -> diagnostic DTO ;
 - aucune valeur de contexte sensible recopiée ;
 - mapping DTO Logging -> contrats Config ;
+- mapping rapports Environment -> DTO safe ;
+- mutations `.env` via services uniquement, sans accès filesystem applicatif ;
+- propagation de `source_changed` / `effective_changed` / `shadowed` / `reload_required` ;
 - AppState : metadata runtime ne change qu'après reload réussi ;
 - policy reveal ;
 - test Logging : validation niveau/target_id/domain, mapping vers callsites KSP fixes et mode multi-niveaux ;
@@ -955,6 +1007,7 @@ Le frontend reste suffisamment mince pour ne pas nécessiter dès le départ un
 - `tsc` strict ;
 - build Vite ;
 - tests de fonctions pures TypeScript uniquement si une logique non triviale apparaît ;
+- parcours manuel reproductible du panneau `.env` (create/update/delete/reload/shadowing) ;
 - parcours manuel reproductible des panneaux et de la matrice Logging.
 
 Si des fonctions UI critiques deviennent suffisamment complexes, un runner de tests sera ajouté seulement au moment du besoin réel.
@@ -968,6 +1021,9 @@ Les commandes sont testées principalement via leurs services Rust sans lancer u
 - splash -> main ;
 - single-instance ;
 - commandes invoke ;
+- mutations `.env` observables via rapport frais, sans accès fichier direct ;
+- démonstration du shadowing process > `.env` ;
+- démonstration d'une nouvelle résolution de `${KSP_LOGS_DIRECTORY:-logs}` après mutation `.env` non shadowée ;
 - hot reload Logging observable ;
 - absence de crash après échec de reload.
 
@@ -1082,36 +1138,45 @@ pre.010  Profils + provenance
          - global/profile/effective
          - provenance sûre
 
-pre.011  Environnement
+pre.011  Environnement — rapports
          - desired/effective/source/shadow
-         - set/remove .env
+         - sensibilité + safe values
-         - feedback process shadowing
+         - table issue uniquement de Config
+         - refresh/reload du rapport
 
-pre.012  Secrets privilégiés
+pre.012  Environnement — management/test .env
+         - create/update via set_dotenv_value
+         - remove via remove_dotenv_value
+         - résultats source/effective/shadow/reload
+         - démonstration process > .env
+         - démonstration placeholder KSP_LOGS_DIRECTORY
+
+pre.013  Secrets privilégiés
          - DTO séparés
          - confirmation explicite
          - reveal transitoire
+         - édition Secret sans préchargement réel
          - audits non-divulgation
 
-pre.013  Logging editor — lecture/DTO
+pre.014  Logging editor — lecture/DTO
          - document/profils/console/files/filters
          - targets/domains
          - mapping types Config -> DTO
 
-pre.014  Logging editor — mutations/persistence
+pre.015  Logging editor — mutations/persistence
          - create/clone/rename/delete profils
          - default_profile
          - mono-fichier/multi-fichiers
          - save_logging_document
 
-pre.015  Logging runtime
+pre.016  Logging runtime
          - sélection profil à appliquer
          - ConfigEnvironment frais
          - load_resolved_logging_config
          - reinitialize + metadata transactionnelle
          - rollback runtime validé
 
-pre.016  panneau Test Logging
+pre.017  panneau Test Logging
          - champ message
          - niveau trace/debug/info/warn/error/tous
          - select target KSP contrôlé
@@ -1120,13 +1185,13 @@ pre.016  panneau Test Logging
          - preuve routing avant/après hot reload
          - preuve bridge frontend
 
-pre.017  robustesse/extensibilité/tests desktop
+pre.018  robustesse/extensibilité/tests desktop
          - invalid source au démarrage
          - audits secrets/Config ownership/tracing
          - tests frontend/Tauri/build
          - ajout futur file_id/editor sans refonte shell
 
-pre.018  clôture
+pre.019  clôture
          - fmt/check/clippy
          - tests ciblés + cargo test --workspace
          - cargo tree pertinents
@@ -1139,7 +1204,7 @@ pre.018  clôture
          - préparation rel.001
 ```
 
-Ce découpage est une **prévision**, pas une obligation de produire exactement dix-huit prereleases. Lorsqu'une tranche atteint son objectif en moins de temps, elle peut absorber le début logique de la suivante ; lorsqu'elle dépasse 20 minutes de façon significative, elle doit préférentiellement être scindée plutôt que compressée. Un défaut déjà livré est corrigé par un `fix` conformément au workflow KSP.
+Ce découpage est une **prévision**, pas une obligation de produire exactement dix-neuf prereleases. Lorsqu'une tranche atteint son objectif en moins de temps, elle peut absorber le début logique de la suivante ; lorsqu'elle dépasse 20 minutes de façon significative, elle doit préférentiellement être scindée plutôt que compressée. Un défaut déjà livré est corrigé par un `fix` conformément au workflow KSP.
 
 ## 19. Dépendances et ordre d'introduction
 
@@ -1205,13 +1270,20 @@ La politique KSP sans lockfile versionné reste inchangée.
 - `default_profile` et profils inspectables ;
 - source/global/profile/effective montrés lorsque pertinent.
 
-### Environnement/secrets
+### Environnement / `.env` / secrets
 
-- rapports desired/effective/source/shadow fonctionnels ;
+- panneau `.env` fonctionnel, pas seulement un affichage de diagnostics ;
-- set/remove `.env` via Config ;
+- rapports desired/effective/source/shadow issus de Config ;
-- shadow process expliqué ;
+- création et modification `.env` via `set_dotenv_value()` ;
+- suppression `.env` via `remove_dotenv_value()` ;
+- résultat de mutation `source_changed` / `effective_changed` / `shadowed` / `reload_required` rendu observable ;
+- rapport rechargé depuis Config après mutation ;
+- priorité process > `.env` démontrée avec un cas de shadowing ;
+- impossibilité de modifier le process parent expliquée ;
+- résolution `${KSP_LOGS_DIRECTORY:-logs}` redémontrée après une mutation `.env` non shadowée, sans résolution frontend ;
 - safe values par défaut ;
 - reveal séparé et explicite ;
+- une valeur Secret existante n'est pas préchargée automatiquement dans l'éditeur ;
 - aucune valeur Secret réelle dans logs/diagnostics/snapshot/state persistant.
 
 ### Logging
@@ -1252,7 +1324,8 @@ crates/ksp-app-config-desk/USAGE.md
 - fenêtre principale ;
 - panneau Documents ;
 - panneau Profils ;
-- panneau Environnement ;
+- panneau Environnement / `.env` ;
+- création/modification/suppression `.env`, reload et shadowing ;
 - reveal secrets ;
 - panneau Logging ;
 - sauvegarde/application ;