v0.1.4-pre.001-fix.002

This commit is contained in:
2026-08-16 09:29:51 +02:00
parent 169ed47fea
commit f8db9f7fb1
2 changed files with 317 additions and 34 deletions

View File

@@ -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 1520 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 1520 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.

View File

@@ -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é ;
- `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=<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 |
| `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 ;