353 lines
12 KiB
Markdown
353 lines
12 KiB
Markdown
<!-- file: prompts/003-V0_1_3_START_PROMPT.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Prompt de démarrage KSP 0.1.3
|
|
|
|
## 1. Contexte de reprise
|
|
|
|
Projet : `khadhroony-solana-project` (KSP).
|
|
|
|
Base requise avant ouverture de cette session :
|
|
|
|
```text
|
|
v0.1.2 stable
|
|
```
|
|
|
|
La release `0.1.2` a introduit `ksp-logging-lib` comme façade KSP unique de logging/tracing runtime. `0.1.3` ne doit pas rouvrir cette architecture ; Config doit consommer ses contrats publics.
|
|
|
|
Release à développer :
|
|
|
|
```text
|
|
0.1.3 — Configuration foundation
|
|
```
|
|
|
|
## 2. Mission
|
|
|
|
Introduire `ksp-config-lib` comme propriétaire des documents de configuration KSP, de leur résolution, de leurs profils, de leur validation et des modifications/persistences explicitement autorisées.
|
|
|
|
La première prerelease est obligatoirement une tranche de brainstorming, audit et planification. Ne pas commencer directement par une implémentation large de Config.
|
|
|
|
## 3. Base architecturale à préserver
|
|
|
|
Dépendances candidates de la nouvelle crate :
|
|
|
|
```text
|
|
ksp-config-lib
|
|
-> ksp-core-lib
|
|
-> ksp-logging-lib
|
|
```
|
|
|
|
Relations interdites :
|
|
|
|
```text
|
|
ksp-core-lib -X-> ksp-config-lib
|
|
ksp-logging-lib -X-> ksp-config-lib
|
|
```
|
|
|
|
`ksp-logging-lib` possède toujours ses propres `LoggingSettings` et son lifecycle `initialize` / `reinitialize`. Config lit/résout ses documents puis construit explicitement les settings publics Logging ; Logging ne lit aucun document Config et ne connaît aucun profil.
|
|
|
|
## 4. Première prerelease obligatoire : `0.1.3-pre.001`
|
|
|
|
Cette tranche doit produire un plan détaillé avant développement fonctionnel.
|
|
|
|
Elle doit notamment :
|
|
|
|
1. auditer l'état réel du workspace stable `0.1.2` ;
|
|
2. réauditer les règles Config déjà présentes dans le dépôt et les archives historiques pertinentes sans les copier aveuglément ;
|
|
3. inventorier les documents de configuration nécessaires à court terme ;
|
|
4. distinguer valeurs globales, valeurs profilées, sélection du profil et composition propre aux exécutables ;
|
|
5. fixer la politique de résolution document -> profil -> env override -> valeur effective ;
|
|
6. fixer la validation, les diagnostics et les erreurs Core nécessaires ;
|
|
7. fixer les opérations de modification/sauvegarde autorisées et leurs garanties d'atomicité ;
|
|
8. fixer la frontière secrets/public/debug ;
|
|
9. définir la relation exacte avec `LoggingSettings` et le hot reload Logging ;
|
|
10. décider si le périmètre Config tient proprement dans une seule release `0.1.3` ou doit être scindé ;
|
|
11. produire `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md` et le plan souple des prereleases suivantes.
|
|
|
|
Le `pre.001` reste une tranche de planification : ne pas ajouter de dépendance fonctionnelle inutilisée et ne pas créer une large surface de code avant validation du plan.
|
|
|
|
## 5. Documents spécialisés
|
|
|
|
La configuration KSP doit être pensée comme plusieurs documents spécialisés plutôt qu'un unique fichier global monolithique lorsque les responsabilités sont distinctes.
|
|
|
|
Le point déjà fixé est notamment :
|
|
|
|
```text
|
|
logging.config.json
|
|
```
|
|
|
|
séparé de la configuration applicative générale.
|
|
|
|
Le `pre.001` doit inventorier les autres documents réellement nécessaires au premier cycle et éviter de créer prématurément des fichiers pour des composants non développés.
|
|
|
|
Les schemas doivent être placés sous :
|
|
|
|
```text
|
|
config/schemas/
|
|
```
|
|
|
|
et les exemples sous :
|
|
|
|
```text
|
|
config/
|
|
```
|
|
|
|
La structure exacte reste à valider dans le plan Config.
|
|
|
|
## 6. Valeurs globales et profils
|
|
|
|
Une valeur qui ne varie pas selon le profil reste hors profils.
|
|
|
|
Exemples historiques déjà retenus comme principe :
|
|
|
|
```text
|
|
logging.logs_directory
|
|
wallets_directory
|
|
```
|
|
|
|
Le `default_profile` est autonome : il sélectionne un profil par défaut mais ne doit pas être artificiellement imbriqué dans chacun des profils.
|
|
|
|
Les fichiers de composition propres à un binaire peuvent sélectionner les documents utilisés et remplacer les profils choisis lorsqu'un besoin concret l'exige.
|
|
|
|
## 7. Variables d'environnement
|
|
|
|
Toutes les variables d'environnement applicatives doivent être namespacées selon leur propriétaire fonctionnel.
|
|
|
|
Pour les composants génériques KSP / `ksp-*` :
|
|
|
|
```text
|
|
KS_*
|
|
KS_PUBLIC_*
|
|
KS_SECRET_*
|
|
```
|
|
|
|
Pour les futures applications/composants bot `kb-*` lorsqu'ils existent :
|
|
|
|
```text
|
|
KB_*
|
|
KB_PUBLIC_*
|
|
KB_SECRET_*
|
|
```
|
|
|
|
Le `pre.001` doit formaliser précisément la correspondance entre document, clé de configuration et override d'environnement.
|
|
|
|
Aucune variable sans préfixe propriétaire ne doit être introduite.
|
|
|
|
## 8. Secrets, public et debug
|
|
|
|
La résolution Config doit distinguer les valeurs exposables de celles qui ne doivent jamais traverser une frontière publique.
|
|
|
|
Politique déjà retenue :
|
|
|
|
- `KS_SECRET_*` / `KB_SECRET_*` : jamais exposés ;
|
|
- `KS_PUBLIC_*` / `KB_PUBLIC_*` : exposables ;
|
|
- autres valeurs : exposition autorisée uniquement dans le contexte debug prévu par les contrats applicatifs.
|
|
|
|
La surface Config ne doit pas transformer cette politique en simple convention documentaire : le plan doit préciser où elle est appliquée et testée.
|
|
|
|
Cela ne change pas la responsabilité de Logging concernant le contenu des messages : `ksp-logging-lib` ne scanne ni ne redacte automatiquement les secrets fournis par ses callers.
|
|
|
|
## 9. Relation Config -> Logging
|
|
|
|
Config peut produire un `ksp_logging_lib::LoggingSettings` à partir de sa configuration effective puis appeler le lifecycle Logging au niveau d'orchestration approprié.
|
|
|
|
Séquence conceptuelle :
|
|
|
|
```text
|
|
documents Config
|
|
-> résolution/profil/env
|
|
-> configuration Logging effective
|
|
-> LoggingSettings
|
|
-> ksp_logging_lib::initialize(...) ou reinitialize(...)
|
|
```
|
|
|
|
Le mécanisme qui détecte un changement de fichier, s'il est introduit plus tard, appartient à Config/application/orchestration ; Logging fournit uniquement sa reconfiguration runtime.
|
|
|
|
`0.1.3-pre.001` doit préciser qui possède le `LoggingGuard` dans les premières compositions concrètes sans créer de singleton global Config inutile.
|
|
|
|
## 10. Validation et erreurs
|
|
|
|
`ksp-config-lib` doit réutiliser :
|
|
|
|
```text
|
|
ksp_core_lib::Error
|
|
ksp_core_lib::ErrorCode
|
|
ksp_core_lib::ErrorContext
|
|
ksp_core_lib::Result<T>
|
|
```
|
|
|
|
Les codes propres à Config appartiennent au domaine Config et ne doivent pas être ajoutés comme connaissance métier à Core.
|
|
|
|
Les diagnostics doivent distinguer autant que nécessaire :
|
|
|
|
- document absent lorsque obligatoire ;
|
|
- syntaxe invalide ;
|
|
- schema/contrainte invalide ;
|
|
- profil demandé absent ;
|
|
- valeur effective invalide ;
|
|
- override d'environnement invalide ;
|
|
- opération de sauvegarde/modification impossible.
|
|
|
|
La nomenclature exacte des ErrorCode est décidée dans le plan puis ajoutée seulement quand chaque erreur devient nécessaire.
|
|
|
|
## 11. Mutation et persistence
|
|
|
|
La configuration n'est pas uniquement un lecteur statique : le périmètre candidat de `0.1.3` comprend les modifications/sauvegardes explicitement autorisées.
|
|
|
|
Le `pre.001` doit décider :
|
|
|
|
- quels documents peuvent être modifiés par API ;
|
|
- quelles valeurs sont read-only ;
|
|
- comment préserver format/version/schema ;
|
|
- comment éviter un fichier partiellement écrit ;
|
|
- comment représenter une modification rejetée ;
|
|
- comment distinguer configuration souhaitée et configuration effective lorsqu'un composant runtime ne peut pas appliquer immédiatement une valeur.
|
|
|
|
Si cette surface rend la release trop large, elle doit être scindée plutôt que comprimée artificiellement.
|
|
|
|
## 12. Frontière application/Tauri
|
|
|
|
`0.1.3` reste une release de bibliothèque Config.
|
|
|
|
La validation desktop complète est prévue ensuite, par défaut dans :
|
|
|
|
```text
|
|
0.1.4 — ksp-app-config-desk
|
|
```
|
|
|
|
Les DTO/bindings Tauri n'appartiennent donc pas automatiquement à `ksp-config-lib`. TS-RS reste principalement une frontière des applications Tauri et ne doit être dérivé dans une crate générique que pour un contrat externe réellement générique et indépendant de Tauri.
|
|
|
|
## 13. Règles Rust et Cargo à conserver
|
|
|
|
Conserver les règles normatives du dépôt, notamment :
|
|
|
|
- Rust 2024 ;
|
|
- `unsafe` interdit ;
|
|
- pas de `unwrap`, `expect`, `panic` dans le code production ;
|
|
- pas d'opérateur `?` ;
|
|
- retours explicites selon les règles Clippy du workspace ;
|
|
- imports de traits seulement lorsque nécessaire, chemins pleinement qualifiés sinon ;
|
|
- pas de `mod.rs` ;
|
|
- pas de `pub(super)` / `pub(in ...)` ;
|
|
- code et Rustdoc en anglais ;
|
|
- documentation Markdown en français ;
|
|
- tests unitaires hors `src` selon la convention du dépôt ;
|
|
- dépendances externes communes déclarées uniquement sous `[workspace.dependencies]` puis consommées avec `.workspace = true` ;
|
|
- versions externes sous contraintes caret de génération compatibles, après vérification de la version actuelle au moment de l'ajout ;
|
|
- ne pas versionner `Cargo.lock`.
|
|
|
|
## 14. Logging dans Config
|
|
|
|
`ksp-config-lib` contient du comportement runtime et doit normalement dépendre de `ksp-logging-lib` pour ses propres événements utiles.
|
|
|
|
Elle ne doit jamais importer directement :
|
|
|
|
```text
|
|
tracing
|
|
tracing-subscriber
|
|
tracing-appender
|
|
```
|
|
|
|
Ses targets KSP explicites utilisent le nom Cargo :
|
|
|
|
```text
|
|
ksp-config-lib
|
|
```
|
|
|
|
Les détails d'une bibliothèque tierce utilisés par Config sont silencieux par défaut ; Config réémet sous son propre target les informations réellement utiles au diagnostic KSP.
|
|
|
|
## 15. Hors scope initial
|
|
|
|
Sauf décision explicite du `pre.001`, ne pas ouvrir dans `0.1.3` :
|
|
|
|
- application desktop Config ;
|
|
- Tauri comme dépendance de `ksp-config-lib` ;
|
|
- Wallet ;
|
|
- Store/PostgreSQL ;
|
|
- RPC/WS/provider ;
|
|
- Program/decoder/execution ;
|
|
- workers/jobs/pipelines ;
|
|
- trading/ML ;
|
|
- watcher générique de tous les fichiers du projet ;
|
|
- service distribué de configuration ;
|
|
- secrets manager distant ;
|
|
- configuration spécifique à des composants qui n'existent pas encore.
|
|
|
|
## 16. Git, versions et deltas
|
|
|
|
Chaque livraison est un delta commité :
|
|
|
|
```text
|
|
pre.NNN
|
|
pre.NNN-fix.NNN
|
|
rel.NNN
|
|
```
|
|
|
|
Cargo utilise les identifiants SemVer sans zéros de tête :
|
|
|
|
```text
|
|
0.1.3-pre.1
|
|
0.1.3-pre.1.fix.1
|
|
```
|
|
|
|
Les noms de deltas/documents peuvent conserver la représentation `pre.001` / `fix.001`.
|
|
|
|
Une correction ultérieure ne réécrit pas un delta déjà livré.
|
|
|
|
Seul le commit final stable reçoit :
|
|
|
|
```text
|
|
v0.1.3
|
|
```
|
|
|
|
## 17. Première action de la session
|
|
|
|
Commencer par `0.1.3-pre.001` : audit, brainstorming et plan de travail.
|
|
|
|
Ne pas traiter ce `pre.001` comme un simple audit passif. Il doit produire les décisions nécessaires au développement des tranches suivantes et une matrice claire des responsabilités Config.
|
|
|
|
## 18. Dernière prerelease
|
|
|
|
La dernière prerelease de `0.1.3` devra :
|
|
|
|
- exécuter les validations finales ;
|
|
- consolider la documentation durable ;
|
|
- nettoyer/archiver uniquement ce que les règles exigent ;
|
|
- préparer le prompt de la release suivante ;
|
|
- vérifier le graphe de dépendances/features ;
|
|
- fermer les TODO de release ou les reporter explicitement ;
|
|
- préparer la livraison `rel.001` et le tag stable après validation utilisateur.
|
|
|
|
## 19. Validations minimales attendues
|
|
|
|
Lorsque les commandes sont applicables :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test --workspace
|
|
cargo tree -p ksp-config-lib
|
|
cargo tree -p ksp-config-lib -d
|
|
cargo tree -p ksp-config-lib -e features
|
|
```
|
|
|
|
Exécuter également tout script d'audit réellement présent dans le dépôt au moment de la validation.
|
|
|
|
Aucune commande non exécutée ne doit être déclarée réussie.
|
|
|
|
## 20. Critère de succès du `pre.001`
|
|
|
|
Le `pre.001` est terminé lorsque nous savons précisément :
|
|
|
|
- quels documents existent dans la première surface Config ;
|
|
- ce qui est global et ce qui est profilé ;
|
|
- comment fonctionne `default_profile` ;
|
|
- comment se résolvent les overrides `KS_*`/`KB_*` ;
|
|
- comment les secrets/public/debug sont classifiés ;
|
|
- quels contrats de lecture/résolution/validation/mutation sont publics ;
|
|
- comment Config construit `LoggingSettings` sans dépendance inverse ;
|
|
- quelles dépendances externes sont réellement nécessaires ;
|
|
- si `0.1.3` reste une seule release ou doit être scindée ;
|
|
- quel est le découpage des prereleases de développement.
|