khadhroony-solana-project/prompts/004-V0_1_4_START_PROMPT.md

<!-- file: prompts/004-V0_1_4_START_PROMPT.md -->
<!-- version: 4 -->

# Prompt de démarrage `0.1.4` — ksp-app-config-desk

## 1. Mission

Ouvrir `0.1.4` uniquement après publication et tag validés de `v0.1.3`.

La mission de cette release est d'introduire `ksp-app-config-desk`, première application desktop spécialisée KSP, afin de valider réellement `ksp-config-lib` et la frontière Tauri sans déplacer la logique Config dans l'application.

La **première prerelease `0.1.4-pre.001` doit être consacrée au brainstorming, à l'audit et au plan détaillé**. Ne pas commencer directement par une implémentation Tauri dispersée. Le `pre.001` doit décider les écrans, commandes, DTO, lifecycle Logging, risques secrets, packaging et découpage des prereleases avant le développement fonctionnel.

## 2. Base requise

Base stable attendue :

```text
v0.1.3
workspace.package.version = "0.1.3"
```

Le workspace doit contenir au minimum :

```text
crates/ksp-core-lib
crates/ksp-logging-lib
crates/ksp-config-lib
config/std.logging.json
config/schemas/std.logging.schema.json
config/schemas/composite.schema.json
config/examples/std.logging.example.json
config/examples/composite.example.json
.env.example
```

Avant toute modification, relire :

```text
README.md
RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
crates/ksp-config-lib/README.md
crates/ksp-config-lib/USAGE.md
crates/ksp-config-lib/TODO.md
crates/ksp-logging-lib/README.md
crates/ksp-logging-lib/USAGE.md
```

Relire également les règles Tauri/Rust/documentation avant de choisir la structure finale de l'application.

## 3. Surface Config stable à réutiliser

`ksp-config-lib 0.1.3` possède déjà :

- `ConfigBootstrapOptions` et les arguments `--cfgpath` / `--schemapath` ;
- `ConfigFileRegistry`, `ConfigFileId` et `--filemap` ;
- `ConfigDocumentEngine` ;
- validation JSON/JSON Schema et invariants sémantiques ;
- globals, profils, `default_profile` et provenance ;
- composites génériques par `file_id` ;
- `ConfigEnvironment` avec priorité process > `.env` > fallback ;
- `${NAME}` / `${NAME:-fallback}` ;
- `Public` / `Internal` / `Secret`, real/safe/provenance ;
- `ResolvedLoggingConfig` et le mapping vers `ksp_logging_lib::LoggingSettings` ;
- `ConfigManagement` ;
- lecture source brute d'un `file_id` connu ;
- `LoggingConfigDocument` et ses sous-contrats typés mutables ;
- persistence atomique de `std.logging.json` ;
- rapports d'environnement desired/effective/shadow ;
- `reveal_effective_environment_value()` / `reveal_dotenv_value()` comme frontières explicites d'accès au réel ;
- `set_dotenv_value()` / `remove_dotenv_value()` ;
- audits workspace de non-contournement Config et couverture `.env.example`.

L'application doit **consommer ces APIs**, pas reproduire leur comportement.

## 4. Architecture cible à auditer pendant `pre.001`

Direction attendue :

```text
ksp-app-config-desk
    -> ksp-config-lib
    -> ksp-logging-lib
    -> ksp-core-lib via les contrats KSP nécessaires
```

L'application est une composition/interface. Elle ne devient pas propriétaire :

- du parsing JSON ;
- des schemas ;
- de `.env` ;
- des placeholders ;
- de la classification des secrets ;
- du mapping Logging ;
- de la persistence Config.

La crate applicative est placée directement sous :

```text
crates/ksp-app-config-desk
```

conformément au layout KSP. Son intégration au workspace et l'organisation interne frontend/Tauri doivent être confirmées dans le plan `pre.001` à partir des règles KSP actives et des contraintes Tauri actuelles.

## 5. Capacités desktop à valider

Le brainstorming `pre.001` doit au minimum cadrer une UI permettant de tester réellement :

### Documents et diagnostics

- afficher les documents Config enregistrés par `file_id` ;
- afficher le source brut lorsqu'un document est invalide afin de permettre sa réparation ;
- distinguer erreurs JSON, schema, sémantiques et erreurs de configuration effective ;
- ne jamais demander à l'UI de reconstruire elle-même les validations.

### Profils

- afficher `default_profile` ;
- lister les profils disponibles ;
- sélectionner explicitement un profil pour inspection/résolution ;
- montrer distinctement source/global/profile/effective lorsque cela est utile à l'opérateur.

### Environnement

- afficher les variables KSP/KSPB via les rapports Config ;
- distinguer desired `.env`, effective, source process/`.env` et shadowing ;
- ne montrer par défaut que `safe_value` ;
- créer/modifier/supprimer une entrée `.env` uniquement via `ConfigManagement` ;
- signaler clairement qu'une valeur process peut masquer une modification `.env` et qu'un process parent ne peut pas être modifié par l'application.

### Secrets

- aucune valeur `Secret` réelle dans un DTO général, un log, un diagnostic ou un état UI persistant par défaut ;
- une action utilisateur explicitement privilégiée peut appeler une méthode `reveal_*` ;
- l'authentification/autorisation de cette action appartient à l'application, pas à `ksp-config-lib` ;
- le `pre.001` doit décider le contrat UX/DTO précis de reveal sans journaliser le secret.

### Logging

- charger `std.logging.json` via Config ;
- éditer ses profils/sinks via les types de management Config ;
- sauvegarder via `save_logging_document()` ;
- construire la configuration effective via `load_resolved_logging_config()` ;
- initialiser/reconfigurer `ksp-logging-lib` ;
- conserver `LoggingGuard` dans l'état applicatif/orchestration approprié ;
- permettre depuis l'UI la création et la modification de plusieurs profils Logging ;
- valider au minimum un profil mono-fichier et un profil multi-fichiers avec sorties séparées plus sortie logiciel/console ;
- permettre la sélection du profil à appliquer, sa sauvegarde puis le rechargement à chaud du runtime Logging ;
- prouver le hot reload par un changement observable du routage/format/sink sans redémarrage de l'application, idéalement au moyen d'événements de test contrôlés ;
- vérifier qu'une erreur de nouvelle configuration ne détruit pas le runtime Logging déjà valide.

Ces capacités constituent le **critère fonctionnel minimal de clôture de la première version de `ksp-app-config-desk`**. Une UI qui ne fait qu'afficher ou sauvegarder `std.logging.json` sans démontrer plusieurs profils et le rechargement effectif n'est pas suffisante pour clore `0.1.4`.

L'architecture de l'application doit en parallèle rester extensible. `0.1.4` peut implémenter un éditeur Logging spécialisé et typé, mais le shell de management, la navigation et l'état applicatif doivent pouvoir accueillir ultérieurement de nouveaux `file_id`, schemas et panneaux/éditeurs spécialisés sans faire de l'application le propriétaire du parsing, de la validation ou de la persistence Config.

## 6. Frontière Tauri

Conserver les règles KSP déjà retenues :

- TS-RS principalement à la frontière de l'application ;
- les DTO Tauri appartiennent à `ksp-app-config-desk`, pas à `ksp-config-lib`, sauf contrat externe générique explicitement justifié ;
- le `pre.001` doit décider et formaliser l’emplacement exact des `#[tauri::command]`; conserver comme direction héritée un adapter Tauri centralisé plutôt que des annotations dispersées ;
- pas de `?`, `unwrap`, `expect` ou `panic` dans les commandes ;
- l'application reste mince et appelle des fonctions/services internes qui réutilisent les crates KSP ;
- aucune utilisation directe de `tracing`, `tracing-subscriber` ou `tracing-appender` pour posséder/configurer le runtime : `ksp-logging-lib` reste la façade et le propriétaire ;
- intégrer à la frontière Tauri le plugin de tracing retenu (`tauri-plugin-tracing` ou successeur explicitement validé) et les adapters nécessaires, sur le modèle éprouvé de khadhroony-bot3 ; cette intégration desktop est l'exception prévue à la règle d'absence d'usage direct des crates `tracing*` ;
- ne pas utiliser `tauri-plugin-log` ni construire une seconde pile basée sur la crate `log` ;
- aucune lecture directe `std::env::var*` pour `KSP_*` / `KSPB_*` ;
- aucune lecture/écriture directe des fichiers physiques Config/`.env`.

Le `pre.001` doit vérifier les versions actuelles de Tauri et des dépendances frontend réellement nécessaires avant leur ajout. Les dépendances communes sont déclarées au niveau workspace lorsqu'elles sont partagées ; aucune dépendance n'est ajoutée sans usage immédiat.

### 6.1 Gabarit Tauri de référence à établir

`ksp-app-config-desk` doit servir de **modèle de référence** pour les futures applications Tauri KSP. `pre.001` doit auditer la base khadhroony-bot3 puis décider précisément ce qui est réutilisé/refondu, notamment :

- organisation SASS/SCSS et dépendances frontend/package utiles ;
- même gabarit visuel initial à affiner et même icône de base tant qu'aucune identité graphique KSP plus spécifique n'est décidée ;
- `vite.config.ts`, `tsconfig.json` et fichiers frontend/build équivalents structurés de manière cohérente avec le modèle éprouvé ;
- package Rust mixte `lib` + `bin`, avec noms de cibles distincts ;
- `main.rs` minimal : verrou single-instance, parsing/bootstrap des éventuels arguments CLI nécessaires, puis appel de la fonction `run` exposée par la bibliothèque applicative ;
- `lib.rs` limité aux déclarations de modules et réexports nécessaires ;
- `tauri.rs` propriétaire de `run`, des wrappers `#[tauri::command]` et des helpers Tauri/démarrage partagés (`init_rustls`, `open_or_focus_window`, etc.) ;
- fonctions métier/fenêtre implémentées dans leurs modules puis appelées par les wrappers de `tauri.rs` ; aucune annotation `#[tauri::command]` dispersée hors de cette frontière ;
- modules spécifiques aux fenêtres nommés `tw_*` (`Tauri window`) sauf meilleure convention explicitement décidée pendant `pre.001` ;
- helpers communs regroupés dans des modules partagés et non copiés entre fenêtres.
- modules/adapters Tauri de tracing repris/refondus depuis le modèle khadhroony-bot3, en utilisant `tauri-plugin-tracing` plutôt que `tauri-plugin-log`, tout en laissant `ksp-logging-lib` posséder la configuration/runtime `tracing`.

Cette réutilisation de bot3 est une référence de conception : le `pre.001` doit vérifier ce qui reste pertinent avec les versions Tauri/Vite/TypeScript actuelles avant intégration.

### 6.2 Splashscreen commun

Le splashscreen et ses fonctionnalités doivent devenir une capacité commune aux applications Tauri KSP :

- même lifecycle de splashscreen réutilisable ;
- comportement configurable plutôt que recopié par application ;
- durée/temporisation configurée via Config/.env ;
- le nom exact de la ou des variables est décidé au moment où le besoin runtime est implémenté, en respectant `KSP_*`/`KSP_PUBLIC_*` selon l'exposition nécessaire ;
- toute nouvelle clé est ajoutée à `.env.example` avec commentaire **dans le même delta que sa première utilisation** ;
- aucune temporisation sensible à l'environnement n'est codée en dur dans chaque application.

### 6.3 Documentation affichée dans l'UI

Ne jamais charger `README.md` comme contenu d'une fenêtre Tauri. Le README reste la documentation du package.

Si `ksp-app-config-desk` retient une vue/fenêtre de présentation, créer un `PRESENTATION.md` dédié et utiliser `markdown-it` comme renderer de référence, après vérification de la version réellement actuelle/compatible avant ajout de la dépendance. `PRESENTATION.md` ne contient aucun lien navigable Markdown ou HTML susceptible de modifier la navigation de la webview ou d'ouvrir/casser une fenêtre.

Si l'application finale est monofenêtre et n'affiche aucune présentation, ne pas créer `PRESENTATION.md` et ne pas ajouter `markdown-it` uniquement par symétrie avec bot3.

## 7. Sécurité et redaction

Le desktop Config est une application de management privilégiée, mais cela ne supprime pas les frontières de sécurité :

- les secrets ne sont jamais loggés ;
- `Debug`/diagnostics utilisent les vues sûres ;
- les APIs `reveal_*` sont appelées uniquement pour une intention explicite ;
- les DTO de reveal sont séparés des DTO ordinaires ;
- l'application doit éviter de conserver inutilement les secrets en mémoire/état UI ;
- une capture d'erreur ne doit pas recopier une valeur réelle dans son message/context ;
- le fichier `.env` reste non versionné ; `.env.example` reste l'inventaire versionné.

## 8. Règles Rust et projet à conserver

Conserver notamment :

- Rust 2024 ;
- `unsafe` interdit ;
- pas de `unwrap`, `expect`, `panic` dans le code production ;
- pas d'opérateur `?` ;
- retours explicites selon Clippy workspace ;
- pas de `mod.rs` ;
- pas de `pub(super)` / `pub(in ...)` ;
- code/Rustdoc en anglais ;
- Markdown projet en français ;
- tests unitaires hors `src` avec structure miroir ;
- tests publics dans `tests/` ;
- dépendances externes communes sous `[workspace.dependencies]` puis `.workspace = true` ;
- versions caret de génération compatibles ;
- aucun `Cargo.lock`/lockfile frontend versionné selon la politique KSP actuelle ;
- chaque delta `0.1.x` est commité ; un défaut livré est corrigé par un `fix`, jamais réécrit silencieusement.
- après toute modification Rust : `cargo fmt --all`, `cargo check --workspace` et `cargo clippy --workspace --all-targets` sont obligatoires avant livraison ;
- pendant une tranche de développement, préférer `cargo test -p <crate>` pour la crate travaillée ; réserver `cargo test --workspace` aux ouvertures/fermetures de session/version et aux contrôles globaux justifiés ;
- exécuter les `cargo tree` pertinents pour les crates modifiées/complétées ;
- toute crate complétée possède un `README.md`; une bibliothèque complétée possède un `USAGE.md` version-neutral centré sur l'API publique avec exemples ; une application Tauri complétée possède un `USAGE.md` décrivant ses fenêtres et leur utilisation.

## 9. Hors scope par défaut de `0.1.4`

Ne pas ouvrir automatiquement :

- Wallet ;
- Store/PostgreSQL ;
- RPC/WS/provider ;
- Program/decoder/executor ;
- workers/jobs/pipelines ;
- trading/ML ;
- nouveaux documents Config pour des composants inexistants ;
- watcher filesystem générique ;
- service distribué de configuration ;
- secrets manager distant ;
- chiffrement maison de `.env` ;
- application de contrôle globale KSP.

Toute extension doit être justifiée dans `pre.001` ou reportée.

## 10. Première livraison attendue : `0.1.4-pre.001`

`pre.001` doit être un **plan de travail**, pas une grosse implémentation.

Il doit produire au minimum :

1. audit exact de la base stable `v0.1.3` ;
2. audit des règles Tauri/app existantes ;
3. choix du layout interne de `crates/ksp-app-config-desk` et de son intégration workspace ;
4. matrice commandes Tauri / services internes / APIs Config appelées ;
5. matrice DTO ordinaires / DTO secrets privilégiés ;
6. modèle d'état applicatif et ownership de `LoggingGuard` ;
7. écrans/panneaux minimums et flux utilisateur ;
8. stratégie de tests Rust, Tauri et frontend, avec tests ciblés par package pendant le développement et `cargo test --workspace` aux frontières globales ;
9. audit du gabarit bot3 à réutiliser/refondre : SASS/SCSS, packages, Vite/TypeScript, icône, layout frontend et splashscreen ;
10. contrat exact `lib` + `bin`, `main.rs`, `lib.rs`, `tauri.rs`, modules `tw_*`, helpers communs et single-instance ;
11. stratégie de splashscreen commun et choix futur de la/des variable(s) Config/.env avec mise à jour obligatoire de `.env.example` lors de leur première utilisation ;
12. dépendances externes réellement nécessaires et versions actuelles vérifiées, dont le plugin Tauri de tracing ; confirmer explicitement l'absence de `tauri-plugin-log` ;
13. hors-scope confirmés ;
14. prévision souple des prereleases, chaque tranche visant environ 15–20 minutes de travail effectif ;
15. décision explicite sur la présence d'une vue de présentation : `PRESENTATION.md` + `markdown-it` si elle existe, aucun fichier/dépendance de présentation si elle n'existe pas ;
16. critères de validation de la release et documentation finale `README.md` / `USAGE.md` / `PRESENTATION.md` conditionnel ;
17. matrice de validation fonctionnelle de clôture couvrant au minimum : création/modification de plusieurs profils Logging, profil mono-fichier, profil multi-fichiers + sortie logiciel/console, sauvegarde, sélection et hot reload observable sans redémarrage ;
18. stratégie d'extensibilité permettant d'ajouter de futurs `file_id`/schemas/éditeurs sans refondre le shell de management ni contourner `ksp-config-lib`.

Ne commencer `pre.002` qu'après validation de ce plan.

## 11. Clôture future de `0.1.4`

La dernière prerelease de `0.1.4` devra comme d'habitude :

- exécuter les validations finales, dont `cargo test --workspace` puisque la release se ferme ;
- consolider la documentation ;
- finaliser le `README.md` de l'application et son `USAGE.md` décrivant chaque fenêtre et son utilisation ;
- finaliser `PRESENTATION.md` uniquement si l'application possède réellement une vue de présentation, et vérifier l'absence de liens navigables Markdown/HTML ;
- démontrer les critères fonctionnels de clôture : plusieurs profils Logging créés/modifiés via l'UI, un profil mono-fichier, un profil multi-fichiers avec sortie logiciel/console, sauvegarde et hot reload observable sans redémarrage ;
- vérifier que l'application reste structurée pour accueillir de futurs documents/schemas Config sans duplication de la logique de `ksp-config-lib` ;
- fermer/report explicitement les TODO ;
- nettoyer/archiver ce qui doit l'être ;
- synchroniser le changelog général lors de la publication stable ;
- produire le prompt de la release suivante ;
- préparer `rel.001` puis le tag stable `v0.1.4` après validation utilisateur.