khadhroony-solana-project/crates/ksp-app-config-desk/README.md

ksp-app-config-desk

ksp-app-config-desk est l'application desktop spécialisée de management et de validation de la configuration KSP.

La crate est un package Tauri mixte :

package : ksp-app-config-desk
lib     : ksp_app_config_desk_lib
bin     : ksp-app-config-desk

Responsabilités

L'application reste une couche d'interface/composition. Les responsabilités de parsing, validation, profils, environnement, .env, secrets et persistence restent dans ksp-config-lib; le runtime Logging restera possédé par ksp-logging-lib.

Le gabarit desktop actif fournit maintenant :

• le verrou single-instance ;
• l'assemblage Tauri centralisé dans src/tauri.rs ;
• les fenêtres splash et main, orchestrées par tw_splash.rs et tw_main.rs ;
• le frontend Vanilla TypeScript + Vite sous frontend/ ;
• SCSS, Bootstrap et Font Awesome ;
• SimpleBar + resize-observer-polyfill pour le scrolling du shell ;
• tauri-plugin-tracing côté Rust et @fltsci/tauri-plugin-tracing côté frontend ;
• les ports dédiés 1430 pour Vite HTTP et 1431 pour le WebSocket de développement ;
• la destination frontend externe commune à Tauri et Vite;
• le bootstrap Config/Logging réel, un AppState durable et le premier contrat Tauri/TS-RS get_app_snapshot;
• le bridge de logging frontend KSP frontend_log.ts, routé par emit_frontend_log vers des targets statiques whitelistés de ksp-logging-lib ;
• le lifecycle configurable splash -> main avec navigation monofenêtre et instrumentation debug/trace des interactions frontend.

Layout frontend

frontend/
├── imgs/
├── sass/
│   ├── _app.scss
│   ├── _bootswatch.scss
│   ├── _fontawesome.scss
│   ├── _simplebar.scss
│   ├── _variables.scss
│   ├── main.scss
│   └── splash.scss
├── ts/
│   ├── frontend_log.ts
│   ├── invoke.ts
│   ├── main.ts
│   └── splash.ts
├── main.html
└── splash.html

Les premiers bindings TS-RS sont générés par les tests ts-rs sous :

frontend/ts/bindings/ksp_app_config_desk/...

Les DTO Rust applicatifs restent la source de vérité et les bindings générés ne sont pas versionnés.

Artefacts frontend

Les artefacts frontend construits ne sont pas versionnés. tauri.conf.json fixe :

../../builds/khadhroony-solana-project/ksp-app-config-desk/dist

vite.config.ts résout cette même destination depuis la racine de la crate, ce qui maintient dist hors du workspace source et l'aligne avec la stratégie .cargo/config.toml pour les artefacts Rust.

Ports desktop

ksp-app-config-desk utilise :

Vite HTTP : 1430
Vite WS   : 1431

Le port HTTP est strict. Les futures applications desk utilisent les couples suivants 1432/1433, 1434/1435, etc.

Dépendances frontend

Les bibliothèques consommées par le bundle applicatif sont déclarées sous dependencies : @fltsci/tauri-plugin-tracing, @fortawesome/fontawesome-free, @tauri-apps/api, bootstrap, simplebar et resize-observer-polyfill.

Les outils de compilation/développement et déclarations de types appartiennent à devDependencies, notamment @tauri-apps/cli, @types/bootstrap, @types/node, sass-embedded, typescript et vite. Les commandes npm directes sont réservées à l'installation ou à la mise à jour de ces dépendances ; le cycle normal de développement et de build est lancé depuis la racine du workspace par Tauri avec la configuration explicite de l'application.

Logging frontend KSP

Le frontend utilise frontend/ts/frontend_log.ts. Les helpers frontendTrace, frontendDebug, frontendInfo, frontendWarn et frontendError, ainsi que le bridge console.*, invoquent la commande Tauri emit_frontend_log.

Le payload ne transporte pas de target tracing libre. Il utilise uniquement les identifiants logiques :

frontend -> ksp-app-config-desk.frontend
main     -> ksp-app-config-desk.frontend.main
splash   -> ksp-app-config-desk.frontend.splash

Rust valide le niveau et le targetId, choisit un callsite statique puis émet exclusivement via les macros de ksp-logging-lib. Le package applicatif n'importe pas directement tracing. Le pont actuel garantit donc le trajet WebView -> Rust tout en conservant l'affichage local des appels console.* dans la console WebKit. Il ne réémet pas encore les événements Rust arbitraires vers la console WebKit : cette direction nécessitera une intégration contrôlée de tauri_plugin_tracing::WebviewLayer dans le subscriber possédé par ksp-logging-lib, sans second subscriber ni boucle avec le bridge KSP. Le panneau manuel de test Logging, ses targets test.* et ses domaines personnalisables restent une surface distincte prévue plus tard.

Bootstrap Config et Logging

Au démarrage, l'application construit ConfigBootstrapOptions, ConfigFileRegistry, ConfigDocumentEngine et ConfigManagement à partir des arguments complets du processus. En développement, le launcher normalise d'abord le current working directory Rust vers la racine du workspace : cargo tauri dev -c ... peut sinon lancer le binaire depuis la crate Tauri, ce qui ferait manquer les chemins Config relatifs config/, config/schemas/ et le .env racine. Cette normalisation ne lit ni ne parse aucun fichier Config elle-même ; l'ownership reste intégralement dans ksp-config-lib. Elle tente ensuite de résoudre le profil Logging par défaut avec un snapshot ConfigEnvironment frais.

Si le document Logging, sa résolution environnementale ou l'initialisation du runtime configuré échoue avant installation du subscriber, Config Desk installe un fallback transitoire en mémoire : console stderr, niveau Info, aucun fichier, aucun span lifecycle. Ce fallback n'est jamais persisté et son diagnostic frontend est limité à domain, code et message.

Le LoggingGuard est conservé dans AppState pour préparer le hot reload ultérieur.

Lifecycle des fenêtres

tw_splash.rs valide l'origine de splash_frontend_ready, ignore les readiness dupliquées et orchestre le passage à main. Les timings sont résolus par ksp-config-lib depuis :

KSP_DESK_SPLASH_MINIMUM_MS=1200
KSP_DESK_SPLASH_FADE_MS=300

Après la readiness frontend, Rust émet fade_in, attend la durée minimale, émet fade_out, attend la durée de fade puis tw_main.rs affiche/focalise main avant destruction du splash. Le backend journalise en debug les valeurs résolues, leur provenance (process, dotenv ou fallback), chaque attente réellement observée et la durée totale. Avec 12000/3000, la durée backend attendue entre readiness et activation de main est donc d'environ 15000 ms. Une valeur splash invalide ne bloque pas le manager : des timings de fallback sûrs restent en mémoire afin que la future surface .env puisse permettre la réparation.

Le shell principal expose les cinq routes de référence Vue d'ensemble, Documents, Profils, Environnement / .env et Logging. Le logo porte déjà l'identité KSP ; le texte du header suit donc la forme Config Desk — <vue active> au lieu de répéter KSP. Les quelques commandes principales restent des pills/tabs à droite ; un dropdown sera préféré lorsqu'une application possède trop de commandes pour conserver ce format lisible. Les routes non encore fonctionnelles affichent un placeholder sans réimplémenter les services prévus par les prereleases suivantes.

Traçabilité frontend

Les actions utilisateur significatives et changements d'état sont journalisés en debug; les opérations plus fines (rendu/remplacement DOM, étapes IPC, animations et événements fréquents) en trace. Le wrapper invoke.ts trace début/fin des commandes sans journaliser leurs arguments, afin de ne pas créer ultérieurement de fuite de valeurs sensibles.

Police du splash

Le splash utilise DOS_Amazigh.ttf (font-family: Dos Amazigh) pour son titre, via le @font-face déclaré dans frontend/sass/splash.scss. Le répertoire frontend/fonts/ documente la provenance et l'empreinte de l'asset de référence. Le lifecycle du splash est désormais actif et utilise cette police pendant la transition vers la fenêtre principale.