v0.1.2-pre.006
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
@@ -23,3 +23,4 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par
|
||||
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt historique ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3` ;
|
||||
- [`002-V0_1_2_START_PROMPT.md`](002-V0_1_2_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.2 — Logging foundation` après publication stable de `0.1.1`.
|
||||
- [`003-V0_1_3_START_PROMPT.md`](003-V0_1_3_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.3 — Configuration foundation` après publication stable de `0.1.2`.
|
||||
|
||||
352
prompts/003-V0_1_3_START_PROMPT.md
Normal file
352
prompts/003-V0_1_3_START_PROMPT.md
Normal file
@@ -0,0 +1,352 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user