135 lines
8.3 KiB
Markdown
135 lines
8.3 KiB
Markdown
<!-- file: crates/ksp-app-config-desk/README.md -->
|
|
<!-- version: 8 -->
|
|
|
|
# `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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
../../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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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.
|