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

Utilisation de ksp-app-config-desk

État actuel

Le gabarit Rust/Tauri et le frontend Vite/TypeScript/SCSS sont présents. Le backend initialise Config, le runtime Logging et AppState. Les panneaux Documents et Profils sont fonctionnels ; les panneaux Environnement/.env, Secrets et Logging restent à compléter.

La fenêtre splash est visible au démarrage. Après readiness du frontend et temporisation résolue par Config, l'application effectue le fade-out, affiche/focalise main puis détruit splash. La fenêtre principale expose immédiatement la navigation monofenêtre de référence.

Première installation des dépendances frontend

Depuis :

crates/ksp-app-config-desk

installer les dépendances déclarées avec la commande de gestion prévue par le projet :

npm i -D
cd ../../

npm i -D sans nom de package installe les dépendances déclarées du package ; la classification dependencies / devDependencies reste celle de package.json. Les lockfiles frontend restent ignorés et ne sont pas versionnés. Après cette installation, les commandes Cargo/Tauri sont exécutées depuis la racine du workspace.

Développement normal

Le frontend n'est pas lancé directement avec npm. KSP est un workspace Rust multi-app : depuis la racine du workspace, la configuration Tauri de l'application doit être sélectionnée explicitement :

cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json

Tauri exécute alors le hook :

npm run dev

Vite écoute strictement sur :

HTTP : 1430
WS   : 1431

Si le port HTTP est déjà occupé, le démarrage doit échouer au lieu de sélectionner silencieusement un autre port.

Build frontend

Le build de l'application passe également par Tauri. Depuis la racine du workspace :

cargo tauri build -c crates/ksp-app-config-desk/tauri.conf.json

beforeBuildCommand déclenche :

npm run build

Vite construit les pages main.html et splash.html vers :

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

Cette destination est résolue depuis la racine de la crate dans vite.config.ts et correspond au frontendDist de tauri.conf.json.

Tracing desktop

tauri-plugin-tracing est enregistré côté Rust et la capability contient tracing:default. Le package frontend associé reste disponible comme adaptateur Tauri, sans installer de subscriber concurrent.

Les logs techniques du frontend passent maintenant par frontend/ts/frontend_log.ts puis la commande Tauri emit_frontend_log. Les identifiants de target autorisés sont :

frontend
main
splash

Ils sont convertis côté Rust vers des targets KSP statiques ksp-app-config-desk.frontend* et émis uniquement via ksp-logging-lib. Un niveau différent de trace, debug, info, warn ou error, ou un targetId non whitelisté, est rejeté avec un CommandErrorDto sûr.

main.ts et splash.ts installent aussi le bridge console.*; l'échec éventuel d'un invoke est écrit uniquement sur la console WebView originale afin d'éviter une boucle de logging. Ce bridge conserve donc les messages JavaScript dans la console WebKit et les transmet vers Rust, mais il ne reflète pas encore les événements Rust généraux dans cette console. attachConsole() du package officiel nécessite que le subscriber Rust publie vers une WebviewLayer; cette couche devra être raccordée plus tard à l'ownership de ksp-logging-lib plutôt que d'installer un subscriber Tauri parallèle.

Bindings TS-RS

Le layout cible est :

frontend/ts/bindings/ksp_app_config_desk/...

Les bindings sont générés au premier DTO Tauri réel ; aucune structure factice n'est ajoutée uniquement pour créer le répertoire.

Bootstrap backend

Les arguments --cfgpath, --schemapath et --filemap=... sont transmis tels quels à ksp-config-lib. En build debug, le launcher replace le current working directory Rust à la racine du workspace avant ce bootstrap afin que les defaults relatifs config/, config/schemas/ et .env désignent les ressources racine même lorsque Tauri lance cargo run depuis la crate de l'application. Le launcher ne lit pas ces ressources lui-même. Le profil Logging initial est le default_profile de std.logging.json.

Si cette configuration ne peut pas être utilisée, l'application doit rester démarrable pour permettre sa réparation : elle utilise alors un fallback Logging console/stderr en mémoire. Le fallback n'écrit aucun fichier de configuration et n'écrase aucune valeur utilisateur.

La commande Tauri get_app_snapshot expose un état sûr du bootstrap. Ses types TypeScript sont générés par cargo test -p ksp-app-config-desk sous frontend/ts/bindings/.

Lifecycle et timings du splash

Les variables communes sont :

KSP_DESK_SPLASH_MINIMUM_MS=1200
KSP_DESK_SPLASH_FADE_MS=300

La priorité est celle de Config : process > .env > fallback. Les valeurs sont lues uniquement via ksp-config-lib. Une valeur non numérique ou hors borne déclenche un fallback runtime en mémoire plutôt qu'un refus de démarrer Config Desk.

Le frontend splash.ts installe son listener puis appelle splash_frontend_ready. Le backend vérifie que l'appel provient réellement de la WebView splash; une readiness dupliquée (par exemple après reload Vite) est ignorée. La durée minimale commence à cette readiness : Rust émet le fade-in, attend minimum, émet le fade-out, attend fade, puis active main. Ainsi KSP_DESK_SPLASH_MINIMUM_MS=12000 et KSP_DESK_SPLASH_FADE_MS=3000 donnent environ 15000 ms de lifecycle backend. Des logs debug indiquent source des deux valeurs, attentes configurées/réelles et durée totale afin de vérifier ce contrat.

Navigation principale

La barre principale contient :

Vue d'ensemble
Documents
Profils
Environnement / .env
Logging

Les vues d'ensemble, Documents et Profils sont fonctionnelles ; Environnement / .env et Logging restent des placeholders jusqu'à leurs tranches fonctionnelles. Le header affiche Config Desk — <vue active> : le logo fournit déjà l'identité KSP. Les commandes principales peu nombreuses utilisent des pills/tabs alignées à droite ; une application plus chargée devra préférer un dropdown. Chaque clic de tab est tracé en trace, l'activation utilisateur significative reste tracée en debug, et chaque remplacement/rendu de section en trace. Les appels Tauri partagés utilisent frontend/ts/invoke.ts, qui journalise le début et la fin d'une commande sans journaliser ses arguments.

Asset font du splash

La police bot3 de référence est DOS_Amazigh.ttf. Vérifier l'asset local contre l'empreinte documentée dans frontend/fonts/README.md ; frontend/sass/splash.scss l'applique au titre du splash.

Panneau Documents

La vue Documents liste les documents de kind Config depuis le registre ksp-config-lib; les schemas ne sont pas codés en dur dans le frontend. DataTables fournit tri, recherche, pagination et sélection simple.

Pour chaque document, le backend expose :

• file_id ;
• filename mappé ;
• schema associé ;
• path résolu par Config ;
• état valide/invalide ;
• étape de diagnostic read, json, schema, semantic, effective ou other.

La sélection charge le source brut via ConfigManagement::read_source(), y compris lorsque le document est invalide mais lisible. Le bouton Valider et sauvegarder envoie le texte à ConfigManagement::save_source_candidate() : aucune écriture frontend directe du fichier n’est effectuée. Un candidat invalide est refusé avant persistence et le diagnostic backend reste l’autorité de validation.

Les clics, sélections, chargements, remplacements DOM et sauvegardes sont tracés via le bridge frontend KSP sans journaliser le contenu du source.

Panneau Profils

La vue Profils charge l'inventaire des documents Config validés qui possèdent default_profile et profiles. Pour le document sélectionné :

• Profil par défaut appelle le backend sans profile_id et doit afficher source de sélection = default_profile ;
• changer Profil inspecté effectue une sélection explicite et doit afficher source de sélection = sélection explicite ;
• Globals source et Profil source affichent les objets validés correspondants ;
• Effective sûre affiche le résultat de résolution environnementale redacted par Config ;
• Provenance top-level indique si chaque clé effective vient des globals ou du profil ;
• Provenance environnement indique JSON Pointer, variable, source et sensibilité sans valeur réelle.

Avec le std.logging.json actuel et KSP_LOGS_DIRECTORY défini dans .env, la provenance attendue pour /logs_directory est KSP_LOGS_DIRECTORY, source dotenv, sensibilité Internal. Le contenu des vues JSON n'est pas recopié dans les logs ; seuls les identifiants de document/profil et métadonnées de résolution sont tracés.