# 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 ` 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.