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, Profils et Environnement/.env sont fonctionnels, y compris les mutations .env create/update/remove et les reveals Secrets privilégiés. Logging expose maintenant un brouillon typé éditable et une persistence atomique ; seul le hot reload runtime reste à 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 cinq vues sont fonctionnelles. Logging charge le contrat typé std.logging.json, permet de modifier son brouillon puis de le persister via Config ; son hot reload runtime reste désactivé jusqu'à pre.016. 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.

Panneau Environnement / .env

La vue Environnement / .env charge get_environment_report, qui projette exclusivement ConfigManagement::environment_report(). La table affiche :

• nom de variable ;
• namespace KSP/KSPB ;
• sensibilité ;
• valeur persisted .env sûre (desired) ;
• valeur effective process-ou-.env sûre ;
• source effective ;
• indicateur shadowed lorsqu'une valeur .env existe mais que le process hérité gagne.

Une valeur Secret doit apparaître redacted (********) dans les colonnes desired/effective. Le bouton Rafraîchir relit le rapport Config.

La zone Management / test .env accepte une variable existante ou un nouveau nom KSP_* / KSPB_*. Créer / Modifier appelle ConfigManagement::set_dotenv_value() et Supprimer appelle ConfigManagement::remove_dotenv_value() ; aucune écriture .env n'est implémentée dans le frontend ou dans la couche Tauri. Après chaque mutation, le rapport est rechargé et les quatre indicateurs Config sont affichés :

source_changed
effective_changed
shadowed_by_process_environment
reload_required

Cliquer une ligne du rapport remplit uniquement le nom de variable. L'ancienne valeur n'est jamais préchargée dans le formulaire. Une saisie KSP_SECRET_* / KSPB_SECRET_* est masquée. Pour une variable Secret sélectionnée, Révéler effective et Révéler .env deviennent disponibles. Ils ouvrent un modal Bootstrap de confirmation avant toute commande Tauri privilégiée.

Le reveal utilise un DTO et une commande séparés des rapports ordinaires. Après confirmation, la valeur réelle est affichée dans un champ transitoire password, masqué par défaut ; Afficher/Masquer ne modifie que le contrôle local. Fermer le modal ou quitter la vue Environnement efface immédiatement la valeur du DOM. Le backend refuse le reveal des namespaces Public/Internal et ne journalise que le nom, la source demandée et la présence/absence d'une valeur.

Le bouton Supprimer ouvre un modal Bootstrap indiquant la variable ciblée. Annuler, la fermeture du modal ou Esc abandonnent l'opération ; Supprimer confirme ensuite l'appel à ConfigManagement::remove_dotenv_value(). Aucun window.confirm() natif n'est utilisé.

Pour valider le shadowing, lancer ponctuellement l'application avec KSP_LOGS_DIRECTORY fourni par le process puis modifier la même variable dans .env depuis le panneau. Le résultat attendu est source_changed=true, effective_changed=false, shadowed_by_process_environment=true, reload_required=false. Le process hérité reste prioritaire et n'est jamais modifié par Config Desk.

Panneau Logging — édition typée

La vue Logging appelle get_logging_document. Le backend charge le document avec ConfigManagement::load_logging_document() et expose :

• file_id, path résolu, format_version, logs_directory, default_profile ;
• chaque profil avec default_filter et span_events ;
• la console (enabled, output, ANSI, format, level, targets, domains) ;
• tous les fichiers (output_id, path, rotation, format, ANSI et filtre) ;
• tous les target_filters globaux.

Le sélecteur Profil édité travaille sur un brouillon local. logs_directory, default_profile, profils, console, file sinks, filtres et target overrides sont modifiables. Créer, Cloner, Renommer et Supprimer agissent d'abord sur le brouillon ; la suppression de profil est confirmée par modal Bootstrap. Sauvegarder envoie un candidat typé à save_logging_document, qui reconstruit les contrats Config et persiste atomiquement après validation. Recharger le document resynchronise le brouillon depuis la source persistée et demande confirmation si des changements non sauvegardés existent. Ni cette action ni Sauvegarder ne reconstruisent le subscriber tracing actif en pre.015 : la configuration persistée prend effet après redémarrage de l'application ; le hot reload sans redémarrage est livré en pre.016. Les messages Cargo/Tauri/Vite affichés par cargo tauri dev sont externes au runtime Logging KSP et ne dépendent pas de console.enabled.