diff --git a/deltas/0.1.4/pre.001-fix.002.md b/deltas/0.1.4/pre.001-fix.002.md new file mode 100644 index 0000000..e472556 --- /dev/null +++ b/deltas/0.1.4/pre.001-fix.002.md @@ -0,0 +1,210 @@ + + + +# 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=`, 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. diff --git a/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md b/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md index 90023c2..3da3c24 100644 --- a/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md +++ b/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md @@ -1,5 +1,5 @@ - + # 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é ; -- `safe_value` desired `.env` ; -- `safe_value` effective ; -- source effective process/`.env` ; -- indicateur shadowed ; -- actions créer/modifier/supprimer `.env` ; -- action privilégiée « Révéler » séparée. +- sensibilité `Public` / `Internal` / `Secret` ; +- `desired_safe_value` persistée dans `.env` ; +- `effective_safe_value` ; +- source effective `process` / `.env` ; +- indicateur `shadowed_by_process_environment` ; +- actions management adaptées à la ligne ; +- 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 ? -valeur effective modifiée ? -shadowed par process ? +Variable : variable existante | nouveau nom KSP_*/KSPB_* +Valeur : champ d'édition, masqué lorsqu'il s'agit d'un Secret +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=` 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 | -| `remove_dotenv_value` | `environment_service` | `ConfigManagement::remove_dotenv_value` | non | +| `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` + 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 - - feedback process shadowing + - sensibilité + safe values + - 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 ; -- set/remove `.env` via Config ; -- shadow process expliqué ; +- panneau `.env` fonctionnel, pas seulement un affichage de diagnostics ; +- rapports desired/effective/source/shadow issus de Config ; +- 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 ;