Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3fd74529d2b65ffb760753bac4e0eaec5131aa0
khadhroony-solana-project/prompts/004-V0_1_4_START_PROMPT.md

18 KiB
Raw Blame History

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 :

v0.1.3
workspace.package.version = "0.1.3"

Le workspace doit contenir au minimum :

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 :

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 :

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 :

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 <crate> 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.
Reference in New Issue View Git Blame Copy Permalink