system_update/plan_8.md

Plan de développement — Tâche 8

Suivi vivant du développement lié à tache8.md. Objectif : préparer puis développer l'app locale Rust/GNOME sans casser la webapp serveur.

---

0. Position actuelle

• Date de démarrage : 2026-06-05.
• État : développement validé par l'utilisateur.
• Décision : le gate qui bloquait le code Rust est levé par validation utilisateur du 2026-06-05. Le scaffold Rust peut démarrer, avec une approche progressive centrée sur le client API avant l'UI GTK/libadwaita.
• Dossier dédié Rust : app_rust/system-update-gnome/.

---

1. Vision suffisante pour démarrer ?

Oui pour un premier incrément.

La direction est claire :

• l'app locale Rust/GNOME est un client du backend system_update ;
• elle ne fait pas de SSH direct au MVP ;
• elle consomme les mêmes JSON que la webapp ;
• elle doit découvrir les capacités du serveur avant d'afficher ses actions ;
• les secrets machines restent côté backend ;
• le token client local sera stocké côté app via trousseau système, quand le scaffold Rust sera autorisé.

Point d'environnement :

• Rust est installé.
• GTK4/libadwaita ne sont pas encore visibles via pkg-config, donc l'UI GNOME complète attendra les paquets système de développement.

---

2. Jalons

8.0 — API commune minimale

• Relire tache8.md et validation_tache8.md.
• Identifier le premier endpoint utile pour app locale.
• Ajouter le type partagé ServerCapabilities.
• Exposer GET /api/capabilities.
• Ajouter un test du contrat capabilities.
• Vérifier TypeScript/tests ciblés.

8.1 — Préparation sécurité client local

• Définir le modèle api_clients côté backend.
• Prévoir scopes : lecture seule, opérateur, admin, debug.
• Prévoir révocation de token.
• Documenter stockage token app locale via keyring.
• Préparer un middleware d'auth API après validation du mode d'amorçage admin.
• Ajouter une commande locale de création de token.
• Activer le middleware sur les routes après choix du mode bootstrap admin.

8.2 — Contrat API app locale

• Stabiliser endpoints machines/state/metrics/hardware.
• Stabiliser snapshots/executions/reports/messages.
• Clarifier pagination et erreurs structurées.
• Clarifier WebSocket/SSE pour sortie live.
• Ajouter /api/system/status.
• Ajouter /api/system/metrics.

8.3 — Scaffold Rust/GNOME

• Créer workspace Rust après validation.
• Utiliser un sous-dossier dédié : app_rust/system-update-gnome/.
• Choisir GTK4/libadwaita direct ou Relm4.
• Implémenter configuration URL serveur.
• Implémenter test de connexion via /api/capabilities.
• Stocker token via keyring.
• Isoler la stratégie token dans src/token_store.rs.

8.4 — UI native MVP

• Première fenêtre GTK/libadwaita derrière feature gui.
• Champ URL serveur.
• Boutons Capabilities, Status, Metrics.
• Zone résultat JSON.
• HeaderBar + Sidebar complète.
• Liste machines.
• Tuile machine compacte.
• Détail machine.
• Lancement apt_update_analyze.
• Lecture rapports/logs réduits.
• Notifications desktop simples.

---

3. Avancement du tour en cours

• Le repo a été inspecté.
• Le manque prioritaire est identifié : endpoint capabilities absent.
• Patch API capabilities appliqué.
• Vérification TypeScript passée.
• Vérification Vitest ciblée passée.
• Vérification Vitest complète passée.

---

4. Résultat du premier incrément

Fichiers ajoutés/modifiés pour le démarrage tâche 8 :

• shared/types.ts : ajout du contrat partagé ServerCapabilities.
• server/services/capabilities.ts : génération du JSON de capabilities.
• server/services/capabilities.test.ts : test du contrat capabilities.
• server/routes/index.ts : exposition de GET /api/capabilities.
• plan_8.md : suivi d'avancement.

Vérifications :

• tsc --noEmit : OK.
• vitest run server/services/capabilities.test.ts : OK.
• vitest run : OK, 11 fichiers de test, 25 tests.

Décision de suite :

• Continuer par 8.1 et 8.2 : sécurité client local, scopes de token, erreurs structurées et endpoints stables.
• Débuter le scaffold Rust dans app_rust/system-update-gnome.
• Garder l'UI GTK/libadwaita pour un incrément suivant, car les bibliothèques système ne sont pas encore installées.

---

5. Validation utilisateur du démarrage dev

• Demande reçue : "ok je valide pour que tu commences le dev".
• tache8.md mis à jour : la tâche passe de design futur à développement progressif.
• validation_tache8.md mis à jour : le code Rust est autorisé dans app_rust/system-update-gnome.
• Scaffold Rust minimal créé dans app_rust/system-update-gnome.
• .gitignore local ajouté pour ignorer target/.
• cargo fmt passé.
• cargo test passé : 7 tests.

---

6. Jalon 8.1 — Sécurité client local

Fichiers ajoutés/modifiés :

• shared/types.ts : scopes API et vues client API sans secret.
• server/db/schema.ts : table api_clients.
• server/db/migrations/0001_api_clients.sql : migration SQLite.
• server/crypto/apiTokens.ts : génération, préfixe, hash HMAC, vérification.
• server/services/apiClients.ts : création/liste/révocation côté service.

Vérifications :

• tsc --noEmit : OK.
• vitest run server/crypto/apiTokens.test.ts server/services/apiClients.test.ts : OK.
• vitest run : OK, 13 fichiers de test, 32 tests.
• migration SQLite temporaire : OK.

Décision :

• Ne pas exposer encore une route publique de création de token sans mécanisme admin.
• Garder authTokens: false dans /api/capabilities tant que l'auth n'est pas réellement activée.

Complément :

• server/auth/apiAuth.ts : middleware requireApiScope prêt à brancher.
• server/auth/apiAuth.test.ts : tests extraction Bearer.
• app_rust/system-update-gnome/src/token_store.rs : séparation token CLI/env/futur trousseau.
• app_rust/system-update-gnome/docs/token-storage.md : choix et règles du stockage token.
• server/cli/createApiClient.ts : création locale d'un token API sans route publique.
• vitest run : OK, 16 fichiers de test, 42 tests.
• cargo test : OK, 11 tests.

---

9. Passe compilation/test

Dernière passe lancée après validation du dossier projet :

• tsc --noEmit : OK.
• vitest run : OK, 16 fichiers de test, 42 tests.
• vite build && tsup : OK.
• cargo fmt : OK.
• cargo test : OK, 11 tests.
• cargo build : OK, sans warning après utilisation de l'identité keyring dans l'aide CLI.

---

10. Test réel client Rust ↔ backend

Backend temporaire lancé avec :

• SU_DB_PATH=/tmp/system-update-rust-client-test.db.
• SU_REPORTS_DIR=/tmp/system-update-rust-client-reports.
• SU_PORT=8787.

Commandes Rust testées :

• cargo run -- capabilities : OK, JSON capabilities reçu.
• cargo run -- status : OK, JSON status reçu.
• cargo run -- metrics : OK, JSON metrics reçu.

Nettoyage :

• backend temporaire arrêté après test ;
• vérification /health après arrêt : connexion refusée, donc port libéré.

---

11. Début interface graphique Rust

Décision :

• UI GTK4/libadwaita ajoutée derrière la feature Cargo gui.
• Le client CLI reste compilable sans GTK.
• Lancement prévu : cargo run --features gui -- gui.

Pré-requis système manquants sur la machine au moment du test :

• pkg-config --modversion gtk4 : paquet absent.
• pkg-config --modversion libadwaita-1 : paquet absent.

Installation à faire dans un terminal utilisateur :

• sudo apt install libgtk-4-dev libadwaita-1-dev.

État :

• Code GUI ajouté.
• Crates GTK/libadwaita résolues via Cargo.
• cargo test sans feature GUI : OK, 12 tests.
• cargo build sans feature GUI : OK.
• cargo check --features gui : bloqué par paquets système manquants (gtk4, pango, cairo, glib-2.0, gio-2.0, gdk-pixbuf-2.0, graphene-gobject-1.0).

Commande utilisateur à lancer dans un terminal interactif :

sudo apt install libgtk-4-dev libadwaita-1-dev

Puis retester :

cd /home/gilles/Documents/projet/system_update/app_rust/system-update-gnome
cargo check --features gui
cargo run --features gui -- --server http://10.0.1.137:8787 gui

Correction suivante :

• Bug observé : GTK recevait --server et affichait Option inconnue --server.
• Cause : adw::Application::run() relisait les arguments du processus.
• Fix : lancement GUI via run_with_args::<&str>(&[]).
• Warning supprimé : import GTK inutilisé.
• Vérification : cargo check --features gui OK, cargo test OK.
• Layout natif aligné webapp : Hermes gauche, Machines centre, terminal API droit, barre de tâche basse.
• /api/machines consommé par la GUI pour remplir la zone centrale.
• Commande CLI machines ajoutée pour tester le même endpoint hors GUI.

---

12. Pause tâche 8

• Date : 2026-06-05.
• Décision utilisateur : terminer la tâche 8 plus tard.
• État au moment de la pause :
  • client Rust CLI fonctionnel ;
  • commandes capabilities, status, metrics, machines ;
  • première GUI GTK/libadwaita disponible derrière --features gui ;
  • layout GUI rapproché de la webapp : Hermes gauche, Machines centre, terminal droit, barre basse ;
  • compilation/test GUI OK après installation des paquets système ;
  • prochaine reprise : améliorer UX native, keyring, vrai modèle machines/actions.

---

7. Notes techniques

• Le backend actuel expose déjà /api/machines, actions APT/reboot et WebSocket de sortie machine.
• L'app locale a besoin de savoir quelles fonctions sont réellement disponibles pour masquer les fonctions futures : Hermes, Docker, post-install, SSH interactif, settings, etc.
• GET /api/capabilities doit retourner un JSON stable, sans secret, exploitable par webapp, Hermes et future app Rust.

---

8. Jalon 8.2 — Endpoints système app locale

Fichiers ajoutés/modifiés :

• shared/types.ts : types SystemStatus et SystemMetrics.
• server/services/system.ts : status et métriques process/hôte.
• server/routes/index.ts : routes GET /api/system/status et GET /api/system/metrics.
• server/services/capabilities.ts : capabilities enrichies avec les endpoints système.
• app_rust/system-update-gnome : commandes CLI status et metrics.

Vérifications :

• tsc --noEmit : OK.
• vitest run server/services/system.test.ts server/services/capabilities.test.ts : OK.
• vitest run : OK, 14 fichiers de test, 35 tests.
• cargo fmt : OK.
• cargo test : OK, 8 tests.