25 KiB
25 KiB
Khadhroony Bot3 — Checklist de clôture de la migration
Périmètre : clôturer la migration de
khadhroony-bot2verskhadhroony-bot3, stabiliserkb-app-demo-desktopet valider l’intégration des crates consolidées.Base de suivi :
0.1.0-pre.055et correctifs suivants.Règle d’utilisation : cocher chaque case uniquement après validation locale explicite. Les sous-cases constituent les critères d’acceptation de la tâche parente.
0. État validé à ce jour
- Les fenêtres historiques principales ont été portées dans
kb-app-demo-desktop. - Les décodeurs, modèles, matérialiseurs et exécuteurs sont consommés depuis
kb-lib. kb-store-coreetkb-store-pgont été fusionnés danskb-store.kb-program-idsest une dépendance explicite du desktop.kb-pipeline-demo-scenariosest une dépendance explicite du desktop.- Le pool WebSocket n’est plus initialisé au démarrage de l’application.
- Le pool WebSocket est créé paresseusement à l’ouverture/utilisation de
demo_ws. - La session WebSocket survit à la fermeture de la fenêtre
demo_ws. - La réouverture de
demo_wsrécupère l’état de la session existante. - La clé
HELIUS_API_KEYchargée depuis.envpermet une connexion Helius réelle. - Les fenêtres dynamiques sont déclarées dans
vite.config.tsetcapabilities/default.json, sans être ajoutées àtauri.conf.json. - La permission de logging est attribuée aux fenêtres dynamiques.
- Les balises HTML mal imbriquées qui rechargeaient
main.htmlont été corrigées. - Les routes de fichiers de logs consolidées produisent une arborescence cohérente.
- L’audit Rust global est propre sur la base testée :
General Rust rule audit: cleanRust export completeness audit: 0 candidate(s)Khadhroony workspace rule audit: clean
1. Corriger immédiatement les deux afficheurs non JSON
1.1 Fenêtre HTTP JSON-RPC
- Remplacer le
@andypf/json-viewerdu bloc Résultat par un<textarea readonly>. - Conserver le résultat RPC sous sa forme textuelle exacte, sans supposer qu’il s’agit toujours de JSON.
- Ajouter exactement un bouton Copier utilisant le presse-papiers.
- Ajouter exactement un bouton Effacer.
- S’assurer que l’effacement vide également le buffer TypeScript interne.
- Donner au textarea une hauteur fixe et un scroll interne.
- Tester successivement :
- réponse JSON structurée ;
- valeur scalaire ;
- chaîne simple ;
- erreur RPC ;
- résultat vide.
1.2 Fenêtre WebSocket
- Remplacer le
@andypf/json-viewerdu bloc Messages par un<textarea readonly>. - Conserver les messages sous forme de journal texte append-only.
- Ajouter exactement un bouton Copier.
- Ajouter exactement un bouton Effacer.
- S’assurer que l’effacement vide le buffer en mémoire et le contenu visible.
- Donner au textarea une hauteur fixe et un scroll interne.
- Vérifier que la réouverture de la fenêtre restaure :
- l’état de connexion ;
- les abonnements actifs ;
- le statut de session ;
- le journal conservé, si cette conservation est voulue.
2. Audit global des composants Copier / Effacer
- Rechercher tous les boutons statiques et boutons injectés dynamiquement :
find kb-app-demo-desktop/frontend \
-type f \( -name '*.html' -o -name '*.ts' \) -print0 |
xargs -0 grep -nE 'Copier|Effacer|clipboard|app-log-clear|attach.*controls'
- Pour chaque bloc de journal ou résultat textuel, garantir une seule paire Copier/Effacer.
- Interdire la coexistence de boutons HTML statiques et de boutons ajoutés par
frontend_log.tssur le même composant. - Vérifier au minimum :
demo_backfill;demo_core_extraction;demo_http;demo_ws;demo_decode_replay;demo_execution_solana_core;demo_execution_spl;- fenêtres SQL ;
- configuration.
- Ajouter un test frontend ou une vérification statique qui échoue lorsqu’un conteneur reçoit plusieurs groupes de contrôles.
3. Uniformiser la position des journaux généraux
- Le journal du Backfill HTTP est placé hors de l’accordéon.
- Le journal d’Extraction core est placé hors de l’accordéon.
- Vérifier que tous les journaux généraux restent visibles lorsque les sections de paramètres sont repliées.
- Déplacer hors des accordéons tout journal général encore imbriqué dans une section de paramètres.
- Conserver dans les accordéons uniquement les sorties strictement liées à une opération ou à un sous-panneau particulier.
- Documenter une règle UI :
- paramètres et formulaires dans les accordéons ;
- journal global et résultat principal sous l’accordéon ;
- hauteur fixe avec scroll ;
- une seule paire Copier/Effacer.
4. Politique JSON commune
- Utiliser
@andypf/json-vieweruniquement lorsque la valeur affichée est garantie comme JSON. - Utiliser un textarea readonly pour :
- journaux ;
- flux de messages ;
- texte brut ;
- réponses dont le format varie ;
- erreurs non structurées.
- Centraliser la création et la mise à jour des viewers JSON dans un helper TypeScript commun.
- Appliquer une hauteur fixe à tous les viewers JSON.
- Appliquer un scroll interne au-delà de la hauteur maximale.
- Éviter qu’un collapse contenant du JSON agrandisse indéfiniment
.card-body. - Vérifier tous les viewers présents dans :
- Configuration ;
- SQL diagnostics ;
- Decode replay ;
- exécutions ;
- autres vues structurées.
- Prévoir une règle pour les valeurs JSON invalides : fallback texte, sans crash de la fenêtre.
5. Stabiliser les fenêtres SQL
5.1 Layout
- Restaurer une disposition pleine largeur pour :
- SQL diagnostics ;
- PostgreSQL raw ;
- PostgreSQL core.
- Ne pas splitter les tableaux principaux en deux colonnes.
- Réserver les colonnes uniquement aux petits panneaux synthétiques si nécessaire.
- Supprimer le scroll horizontal global de la page.
- Autoriser un scroll horizontal local uniquement dans
.table-responsivelorsque réellement nécessaire. - Vérifier que le listing des tables utilise toute la largeur disponible.
- Comparer le rendu avec Bot2 pour éviter une régression fonctionnelle ou ergonomique.
5.2 Navigation et IPC
- Les balises de navbar mal fermées ont été corrigées.
- Vérifier chaque bouton et chaque onglet des quatre fenêtres SQL.
- Confirmer qu’aucune action ne recharge
main.html. - Confirmer qu’aucun clic ne déclenche une navigation implicite via un
<a>parent. - Vérifier les formulaires et boutons sans
type="button"susceptibles de soumettre un formulaire. - Revalider les appels IPC lors de rechargements Vite, sans considérer l’ancien défaut comme actif s’il n’est plus reproductible.
5.3 Initialisation PostgreSQL
- Décider définitivement quand exécuter
initialize_postgres_schema_for_startup:- au démarrage avec compte rendu dans le splash ; ou
- à la première ouverture d’une fenêtre SQL.
- Supprimer le code mort si l’initialisation de démarrage est abandonnée.
- Sinon, brancher réellement :
initialize_postgres_schema_for_startup;emit_sql_startup_table_report;emit_sql_startup_error;emit_sql_startup_splash.
- Ne pas conserver durablement des helpers publics ou
pub(crate)inutilisés. - Ajouter des tests de schéma présent, incomplet et inaccessible.
6. Corriger les échecs Metaplex Token Metadata
6.1 Constat issu des logs pre.055
- Le pipeline sélectionne correctement le décodeur
metadata_metaplex_token_metadata. - Le programme canonique est reconnu :
metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
- L’archive analysée contient 10 échecs explicites de validation de comptes :
- 8
create_metadata_account_v3 account 1 has invalid signer/writable flags; - 2
transfer account 1 has invalid signer/writable flags.
- 8
6.2 Diagnostic à effectuer
- Extraire pour chaque transaction échouée :
- signature ;
- slot ;
- chemin d’instruction ;
- instruction outer/inner ;
- données brutes ;
- liste ordonnée des comptes ;
- flags signer/writable réellement reconstruits.
- Vérifier si
account 1désigne :- l’index dans les comptes de l’instruction ;
- l’index global du message ;
- un index décalé par le program ID ;
- un compte issu d’une Address Lookup Table.
- Vérifier la reconstruction des flags pour :
- comptes statiques ;
- comptes chargés par ALT ;
- instructions internes ;
- comptes dupliqués ;
- invocation CPI.
- Comparer les contrats du décodeur avec :
- l’IDL officiel
token_metadata.json; - les builders/generated instructions Metaplex ;
- des transactions mainnet réelles.
- l’IDL officiel
- Vérifier si les contraintes imposées sont trop strictes pour les CPI, notamment lorsqu’un programme appelant transmet un compte avec des privilèges supérieurs ou différents.
- Distinguer clairement :
- compte absent ;
- nombre de comptes invalide ;
- signer manquant ;
- writable manquant ;
- privilège supplémentaire acceptable ;
- privilège incompatible.
6.3 Correctif et tests
- Corriger la matrice de comptes de
create_metadata_account_v3. - Corriger la matrice de comptes de
transfer. - Ajouter les transactions réelles de l’archive comme fixtures bornées ou vecteurs synthétiques équivalents.
- Ajouter un test de CPI pour chaque instruction concernée.
- Ajouter un test avec Address Lookup Table si applicable.
- Ajouter un test où un compte possède un privilège supérieur acceptable.
- Ajouter un test qui refuse réellement un signer/writable manquant.
- Rejouer les signatures échouées avec
forceReplay=true. - Obtenir
failed=0pour les cas désormais supportés. - Classer en
Unsupportedplutôt qu’enFailedtoute variante volontairement hors périmètre mais valide sur chaîne. - Vérifier la matérialisation après correction du décodage.
6.4 Observabilité du décodeur
- Enrichir le diagnostic avec :
- nom du rôle attendu ;
- index du compte ;
- pubkey ;
- flags attendus ;
- flags observés ;
- contexte outer/inner.
- Afficher ces diagnostics dans la fenêtre Decode replay.
- Ajouter un bouton Copier pour les diagnostics détaillés.
- Ne pas exposer de données sensibles dans les logs.
7. IDL Metaplex Token Metadata
- Placer le snapshot officiel dans le workspace :
idls/metaplex_token_metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.json
- Conserver le fichier source/provenance associé.
- Documenter :
- URL officielle ;
- commit ou SHA du blob ;
- version IDL
1.14.0; - program ID canonique.
- Ajouter un script de rafraîchissement déterministe.
- Ajouter un test vérifiant que l’IDL est du JSON valide.
- Ajouter un test comparant les discriminants couverts par le décodeur avec l’IDL.
- Ne pas utiliser l’IDL comme seule source normative lorsque le programme ou les generated builders divergent.
8. Configuration .env et ordre de résolution
8.1 kb-config
dotenvyappartient àkb-config, pas au desktop.- Vérifier l’API publique finale et ses noms.
- Appliquer et tester l’ordre :
- environnement déjà présent dans le processus ;
- fichier explicitement indiqué par
KB_ENV_FILE; .envà la racine du workspace ;- fallback
${VAR:-fallback}; - variable non résolue conservée ou erreur selon le contrat du champ.
- Garantir qu’un
.envne remplace jamais une variable déjà injectée par le shell, systemd, Docker, CI ou IDE. - Définir le comportement si
KB_ENV_FILEpointe vers un fichier absent. - Définir le comportement si
.envest absent. - Définir le comportement des lignes invalides.
- Interdire l’impression de valeurs secrètes dans les diagnostics.
- Ajouter des tests isolés et sérialisés pour éviter les collisions d’environnement global entre tests.
8.2 kb-app-demo-desktop
- Retirer toute lecture ou tout chargement
.envrésiduel du desktop. - Ne conserver que l’appel à l’API de chargement de
kb-config. - Afficher dans la fenêtre Configuration la provenance des sources sans afficher les secrets :
- environnement processus ;
- fichier
.envchargé ; - fallback ;
- non résolu.
- Vérifier que l’application démarre sans clé Helius.
- Vérifier que l’utilisation d’un endpoint Helius sans clé produit une erreur ciblée.
- Vérifier qu’une clé valide dans
.envpermet HTTP et WebSocket Helius.
8.3 kb-pipeline-demo-scenarios
- Ne pas dépendre directement de
dotenvy. - Centraliser l’initialisation par
kb-configlorsque les scénarios sont lancés directement. - Réduire progressivement les appels directs
std::env::var. - Introduire des structures typées pour :
- SPL Token classique ;
- ATA ;
- Token-2022 ;
- ElGamal Registry ;
- scénarios Solana Core.
- Permettre l’injection des valeurs dans les tests sans modifier l’environnement global.
- Vérifier que les variables externes historiques
TOKEN_2022_*peuvent rester nommées ainsi, tout en utilisanttoken2022dans les modules Rust internes.
8.4 Tâche ultérieure kb-store
- À reporter : décider si les chemins/URLs de base sont entièrement résolus par
kb-configavant construction dekb-store. - Ne pas faire charger
.envdirectement parkb-store. - Prévoir une configuration typée déjà résolue pour PostgreSQL et les futures bases.
- Étudier la séparation future des targets de logs
kb-store.coreetkb-store.postgres.
9. Cycle de vie WebSocket
- Aucun pool WebSocket au démarrage général.
- Création paresseuse lors du premier accès.
- Pool conservé dans
AppState. - Fermeture de
demo_wssans fermeture de la session. - Récupération du statut à la réouverture.
- Utiliser
disconnect_demo_ws_app_statelors de la fermeture globale de l’application. - Ne pas l’appeler lors de la simple destruction de
demo_ws. - Tester la fermeture explicite depuis la fenêtre.
- Tester le timeout de session.
- Tester la fermeture de l’application avec session et abonnements actifs.
- Vérifier qu’aucune tâche Tokio ni relay ne reste suspendu après arrêt.
- Éliminer le warning
dead_codede façon fonctionnelle, sans supprimer le hook requis.
10. Menu principal et cohérence visuelle
- Réordonner définitivement le dropdown des fenêtres selon les groupes suivants :
- Configuration ;
- Transport : HTTP, WebSocket, Backfill ;
- Pipeline : Extraction core, Decode replay ;
- SQL : diagnostics, raw, core, replay ;
- Exécution : Solana Core, SPL.
- Ajouter des séparateurs ou titres de groupes non cliquables.
- Vérifier que chaque fenêtre possède le logo non cliquable.
- Vérifier particulièrement
demo_execution_solana_core. - Garder les descriptions longues dans le contenu principal et non dans la navbar.
- Vérifier les deux textes :
- « System Program uniquement — simulation-first et replay post-exécution » ;
- « Memo, SPL Token classique, Token-2022 et ATA — simulation-first et replay post-exécution ».
- Uniformiser titres, sous-titres, marges et hauteurs de navbar.
11. Vérifier les options de la fenêtre Exécution SPL
- Auditer toutes les valeurs de
demo_execution_spl.html. - Vérifier leur correspondance exacte avec les parsers et enums Rust.
- Remplacer les valeurs internes historiques
token_2022partoken2022lorsqu’elles ne constituent pas un contrat externe. - Conserver uniquement les variables d’environnement externes
TOKEN_2022_*si elles sont déjà documentées et utilisées. - Vérifier chaque scénario :
- Memo v4 ;
- SPL Token classique ;
- Token-2022 ;
- ATA.
- Vérifier que Memo v1 et v3 restent non exécutables.
- Vérifier les scénarios publics Token-2022 réellement supportés par l’exécuteur.
- Retirer ou désactiver toute option UI sans implémentation réelle.
- Ajouter un test qui compare la liste HTML/TypeScript avec l’inventaire Rust exposé.
12. Façades consolidées et nomenclature
- Exécuter une recherche uniquement sur les fichiers Rust :
find kb-app-demo-desktop -type f -name '*.rs' -print0 |
xargs -0 grep -nE 'kb_store_pg|kb_store_core|kb_model|kb_decoder_|kb_materializer_|kb_executor_|token_2022|_2022'
- Aucun ancien crate Bot2 ne doit subsister.
- Tous les modèles, décodeurs, matérialiseurs et exécuteurs doivent passer par
kb-lib. - Tout le stockage doit passer par
kb-store. - Les modules Rust internes utilisent
token2022, jamaistoken_2022. - Les constantes utilisent
SPL_TOKEN2022_*selon la nomenclature dekb-program-ids. - Les variables d’environnement externes
TOKEN_2022_*peuvent rester. - Vérifier tous les
export_touniquement dans les.rs:
find kb-config kb-lib kb-app-demo-desktop \
-type f -name '*.rs' -print0 |
xargs -0 grep -n 'export_to'
- Corriger les chemins TS-RS résiduels qui imitent des anciens noms de crates.
- Supprimer les fichiers de bindings orphelins générés par les anciens chemins.
13. Logging
- La sortie console compacte est de nouveau active.
- Les routes consolidées produisent une arborescence cohérente.
- Vérifier la console pour chaque profil configuré.
- Vérifier qu’aucune route n’utilise un ancien target Bot2.
- Vérifier l’absence de dossiers vides créés pour des targets inexistants.
- Ajouter un test de complétude des routes par rapport aux targets publics actuels.
- Vérifier la cohérence tiret/underscore entre target et répertoire.
- Décider ultérieurement si
kb-storedoit produire :kb-store/core;kb-store/postgres.
- Ne pas traiter cette séparation comme bloquante pour la clôture de la migration.
14. Nettoyage des warnings Rust
- Résoudre le warning
DemoDecodeReplayProgressPayloadinutilisé par un usage réel ou un ajustement de visibilité justifié. - Résoudre le warning
initialize_postgres_schema_for_startupinutilisé après décision sur l’initialisation SQL. - Résoudre le warning
disconnect_demo_ws_app_stateinutilisé en le branchant sur l’arrêt global. - Résoudre les helpers SQL privés inutilisés en les utilisant ou en les supprimant si le flux est abandonné.
- Ne pas supprimer une fonction prévue uniquement pour faire taire un warning sans décision architecturale.
- Obtenir
cargo test -p kb-app-demo-desktopsans warning propre au code applicatif.
15. Clippy et macros Tauri
- Traiter en dernier les erreurs
clippy::question_mark_usedprovenant des expansions#[tauri::command]async. - Confirmer qu’aucun
?interdit n’existe dans le code source métier. - Choisir une solution localisée et documentée :
- allowance au niveau du module adaptateur Tauri ; ou
- configuration ciblée pour le code généré ; ou
- exception d’audit explicite pour les macros externes.
- Ne pas rendre les commandes synchrones uniquement pour satisfaire Clippy.
- Ne pas désactiver le lint à l’échelle du workspace.
- Ajouter une note dans
RUST_RULES.mdexpliquant l’exception du code généré Tauri. - Obtenir finalement :
cargo clippy --all-targets
sans erreur.
16. Validation fonctionnelle de chaque fenêtre
- Splash : affiche uniquement les composants réellement initialisés au démarrage, puis est détruit.
- Main : menu ordonné, tous les liens fonctionnels.
- Configuration : viewers JSON bornés, provenance de configuration lisible, secrets masqués.
- HTTP : méthodes, paramètres, résultat texte, Copier/Effacer.
- WebSocket : connexion, abonnements multiples, restauration, messages texte, déconnexion.
- Backfill : anciens/nouveaux historiques, annulation, journal permanent, résultat.
- SQL diagnostics : pleine largeur, refresh, erreurs.
- SQL raw : pleine largeur, tables et compteurs.
- SQL core : pleine largeur, tables et compteurs.
- SQL replay : filtres, DataTables, CSV, onglets.
- Extraction core : campagne, annulation, journal permanent.
- Decode replay : 7 décodeurs, matérialiseurs, diagnostics, annotations.
- Exécution Solana Core : simulation, envoi contrôlé, replay post-exécution.
- Exécution SPL : Memo v4, Token, Token-2022, ATA.
- Fermeture et réouverture répétées de toutes les fenêtres dynamiques.
- Vérification qu’aucune fenêtre dynamique ne démarre automatiquement.
17. Tests de scénarios hors Tauri
- Déplacer ou dupliquer les scénarios métier importants dans
kb-pipeline-demo-scenarios. - Couvrir Solana Core.
- Couvrir Memo v4.
- Couvrir SPL Token classique.
- Couvrir ATA.
- Couvrir Token-2022.
- Couvrir ElGamal Registry lorsque validable.
- Couvrir Metaplex Token Metadata.
- Tester sans démarrer Tauri.
- Tester avec configurations injectées plutôt qu’avec environnement global lorsque possible.
18. Sécurité des secrets et fichiers locaux
- Vérifier que
.envest ignoré par Git. - Conserver
.env.exampleversionné sans secret. - Vérifier l’historique Git pour s’assurer qu’aucune clé Helius réelle n’a été ajoutée.
- Masquer les valeurs sensibles dans les logs et dans la fenêtre Configuration.
- Ne jamais inclure
.envdans les archives delta. - Ajouter une validation de démarrage qui signale la présence/absence d’une clé sans l’afficher.
19. Validation technique finale
cargo fmt --allcargo check -p kb-configcargo test -p kb-configcargo check -p kb-pipeline-demo-scenarioscargo test -p kb-pipeline-demo-scenarioscargo check -p kb-app-demo-desktopcargo test -p kb-app-demo-desktopcargo check --workspacecargo test --workspacepython3 scripts/audit_rust_workspace_rules.pycargo clippy --all-targetsaprès traitement de l’exception Tauri.cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json- Vérification manuelle de toutes les fenêtres.
- Vérification réelle HTTP Helius.
- Vérification réelle WebSocket Helius.
- Rejeu Metaplex avec
failed=0sur les cas corrigés.
20. Documentation et clôture
- Mettre à jour
README.mdavec l’architecture Bot3 finale. - Mettre à jour
ROADMAP.mdavec les points réellement clôturés et les reports. - Mettre à jour
CHANGELOG.mdavec toutes les prereleases et fixes. - Documenter la politique
.envet l’ordre de résolution. - Documenter le cycle de vie HTTP/WebSocket.
- Documenter les fenêtres dynamiques, Vite et capabilities.
- Documenter les conventions de viewers JSON et de journaux texte.
- Documenter l’IDL Metaplex et sa provenance.
- Documenter les tâches reportées :
- résolution de configuration de base dans
kb-store; - séparation des logs
kb-store.core/kb-store.postgres; - améliorations non bloquantes.
- résolution de configuration de base dans
- Préparer le prompt complet de la session suivante.
- Livrer le dernier delta de migration.
- Effectuer le commit Git de clôture.
- Taguer la prerelease ou version de clôture selon la convention retenue.
21. Critères de clôture obligatoires
La migration ne peut être déclarée terminée que lorsque toutes les conditions suivantes sont satisfaites :
- Toutes les fenêtres historiques requises sont présentes et fonctionnelles.
- Aucun ancien crate Bot2 n’est référencé.
- Aucune erreur de compilation ou de test.
- Audits Rust et workspace propres.
- Aucun warning applicatif non justifié.
.envest centralisé danskb-configet sa priorité est testée.- HTTP et WebSocket Helius fonctionnent avec une clé locale non versionnée.
- Les erreurs Metaplex observées sont corrigées ou classées explicitement et correctement.
- Les fenêtres SQL n’ont ni navigation involontaire ni layout régressif.
- Chaque journal/résultat texte possède une seule paire Copier/Effacer.
- Les viewers JSON sont bornés en hauteur et réservés au JSON réel.
- Le cycle de vie WebSocket est validé jusqu’à l’arrêt global.
- La documentation de clôture et le prompt suivant sont livrés.