# Consigne de dev — App locale Rust/GNOME connectée au serveur > **Type** : mission de **développement progressif** après validation utilisateur du 2026-06-05. > **Langue** : français. > **Livrable final attendu** : app locale Rust/GNOME développée par jalons, en commençant par un client API minimal. --- ## 0. Contexte La webapp `system_update` pilote des machines Linux via un backend central : - SSH agentless ; - snapshots JSON ; - exécutions ; - logs/rapports ; - Hermes/MCP ; - terminal ; - paramètres ; - schedules. La tâche 8 vise une évolution : créer une **application locale native** en Rust, style GNOME/libadwaita, qui se connecte au serveur `system_update` via API et reprend une partie de l'UI du frontend, sans nécessiter de navigateur web. Validation utilisateur : - 2026-06-05 : le démarrage du développement est validé. - La première phase crée un scaffold Rust compilable et un client API minimal. - L'UI GTK4/libadwaita attend l'installation des bibliothèques système `gtk4` et `libadwaita-1`. --- ## 1. Objectif Concevoir une application locale : - développée en Rust ; - UI GTK4/libadwaita ou équivalent GNOME moderne ; - thème aligné avec le design system Gruvbox seventies ; - communication API avec le backend `system_update` ; - affichage des machines, tuiles, rapports, logs, paramètres ; - exécution des actions via le backend, jamais SSH direct par défaut ; - support optionnel Hermes via le backend ; - mode desktop local plus confortable qu'un navigateur pour usage quotidien. --- ## 2. Périmètre fonctionnel ### MVP app locale - configuration URL serveur ; - authentification par token/API key ; - liste des machines ; - vue état courant machine ; - tuiles machine compactes ; - détail machine ; - lancement `apt_update_analyze` ; - affichage actions en cours ; - lecture rapports ; - lecture logs réduits ; - notifications desktop simples. ### Fonctions avancées - terminal de logs live via WebSocket/SSE ; - vrai terminal SSH interactif via backend, si activé ; - vue Hermes native ; - paramètres frontend/app ; - scripts post-install ; - Docker Compose ; - mode offline partiel : cache lecture seule des derniers états ; - tray icon ; - notifications GNOME ; - import/export configuration serveur. --- ## 3. Architecture cible ```text ┌──────────────────────────────────────────────┐ │ App locale Rust/GNOME │ │ - UI libadwaita │ │ - stockage config local │ │ - client HTTP/WebSocket │ │ - cache lecture seule │ └───────────────────┬──────────────────────────┘ │ HTTPS / WS / SSE ┌───────────────────▼──────────────────────────┐ │ Backend system_update │ │ - API REST stable │ │ - événements live │ │ - auth clients │ │ - stockage JSON/logs/rapports │ │ - orchestration SSH │ │ - proxy Hermes/MCP │ └───────────────────┬──────────────────────────┘ │ SSH ┌───────────────────▼──────────────────────────┐ │ Machines Linux │ └──────────────────────────────────────────────┘ ``` Règle : > L'app Rust ne fait pas de SSH direct au MVP. Elle demande au backend de lancer les actions et consomme les JSON, logs et événements. --- ## 4. Stack technique à étudier ### Rust - `gtk4` ; - `libadwaita` ; - `glib`/`gio` ; - `reqwest` ou client HTTP async compatible ; - `tokio` si retenu ; - WebSocket via crate adaptée ; - `serde`/`serde_json` ; - `keyring` pour stocker le token localement ; - `directories` pour chemins de config/cache ; - `tracing` pour logs app. Alternative à comparer : - `relm4` pour architecture UI plus structurée ; - `iced` si GTK/libadwaita devient trop contraignant, mais moins GNOME natif. ### Design system GNOME Réutiliser : - `design_system/tokens/tokens.gnome.css` ; - `design_system/tokens/tokens.json`. À concevoir : - mapping tokens CSS web → libadwaita ; - widgets équivalents aux tuiles ; - couleurs dark/light ; - icônes SVG compatibles GTK ; - densité proche du frontend. --- ## 5. API backend nécessaire L'API doit rester commune au frontend web, Hermes/MCP et app locale. Endpoints à utiliser : ```text GET /api/system/status GET /api/system/metrics GET /api/machines GET /api/machines/:id/state GET /api/machines/:id/hardware GET /api/machines/:id/metrics GET /api/machines/:id/snapshots GET /api/machines/:id/executions GET /api/machines/:id/reports GET /api/machines/:id/messages POST /api/machines/:id/actions GET /api/reports GET /api/reports/:id GET /api/artifacts/:id/important-lines GET /api/settings PATCH /api/settings GET /api/events GET /api/ws/machines/:id/output ``` À ajouter ou clarifier côté backend : - version d'API ; - pagination ; - erreurs structurées ; - auth token dédiée client local ; - droits par action ; - révocation token ; - audit des clients ; - limitation de débit ; - endpoint capabilities. Exemple capabilities : ```json { "apiVersion": "1", "features": { "machines": true, "actions": true, "terminalOutput": true, "interactiveSsh": false, "hermes": true, "settings": true } } ``` --- ## 6. Sécurité Règles : - token stocké dans le trousseau local via `keyring`, pas en clair dans un fichier ; - HTTPS recommandé hors localhost ; - permissions minimales par token ; - actions dangereuses confirmées dans l'app ; - les secrets SSH/sudo restent uniquement côté backend ; - l'app locale ne reçoit jamais les credentials machines ; - logs locaux sans secret ; - blocage si certificat/host inconnu selon politique choisie. Profils de token : - lecture seule ; - opérateur : refresh + actions non destructives ; - admin : actions dangereuses + paramètres ; - debug : accès logs étendus. --- ## 7. UX native proposée ### Layout desktop ```text ┌────────────────────────────────────────────────────────────────────┐ │ HeaderBar System Update [search] [refresh] [settings] │ ├───────────────┬────────────────────────────────────────────────────┤ │ Sidebar │ Machines │ │ │ ┌────────────────────────────────────────────────┐ │ │ Overview │ │ ● vm_mqtt debian · vm · APT 4 · Docker 1 │ │ │ Machines │ │ CPU 0.08 · RAM 26% · / 29% │ │ │ Reports │ │ [analyze] [upgrade] [reboot] [report] │ │ │ Hermes │ └────────────────────────────────────────────────┘ │ │ Settings │ │ ├───────────────┴────────────────────────────────────────────────────┤ │ StatusBar connected · 4 machines · jobs 1 · hermes ok · 06:42 │ └────────────────────────────────────────────────────────────────────┘ ``` ### Détail machine ```text ┌────────────────────────────────────────────────────────────────────┐ │ vm_mqtt debian 13 · vm · qemu │ ├────────────────────────────────────────────────────────────────────┤ │ Summary APT 4 · reboot no · Docker 1 · warnings 1 │ │ Health CPU 0.08/4c · RAM 26% · / 29% │ │ │ │ Tabs: [System] [Docker] [Post-install] [Hardware] [Logs] [Reports] │ │ │ │ System │ │ packages to update... │ └────────────────────────────────────────────────────────────────────┘ ``` ### Paramètres ```text ┌────────────────────────────────────────────────────────────────────┐ │ Settings │ ├───────────────┬────────────────────────────────────────────────────┤ │ Server │ Server URL [ https://10.0.0.X:8787 ] │ │ Appearance │ API token [ ************* ] [test] │ │ Actions │ Theme [ Gruvbox dark ] │ │ Notifications │ Cache [ enabled ] │ │ Security │ Notifications [ enabled ] │ └───────────────┴────────────────────────────────────────────────────┘ ``` --- ## 8. Différences avec la webapp L'app locale ne doit pas être une copie exacte. À garder : - logique métier backend ; - contrats JSON ; - tuiles machine ; - design tokens ; - rapports/logs ; - validations actions. À adapter : - navigation GNOME avec HeaderBar/Sidebar ; - notifications desktop ; - stockage token via trousseau ; - raccourcis clavier natifs ; - possibilité de tray icon ; - fenêtres modales natives. --- ## 9. Livrables attendus À produire sous `docs/` : 1. Architecture app locale ↔ backend. 2. Choix stack Rust/GNOME argumenté. 3. Contrat API nécessaire. 4. Modèle de sécurité/token. 5. Mapping design system web → GNOME. 6. Maquettes ASCII vues principales. 7. Plan de cache/offline lecture seule. 8. Découpage en sous-jalons. --- ## 10. Définition de terminé - L'app locale peut être développée sans modifier la logique SSH. - Le backend expose les API nécessaires. - Les credentials machines restent côté backend. - L'UI native respecte le thème Gruvbox seventies. - Les actions dangereuses restent validées. - La webapp et l'app Rust partagent les mêmes contrats JSON. - Le scaffold Rust est compilable. - Le client API peut tester `/api/capabilities`. - L'UI GNOME est développée ensuite, sans déplacer la logique SSH hors du backend. --- ## 11. Technos à utiliser — checklist - [ ] Rust. - [ ] GTK4. - [ ] libadwaita. - [ ] `gtk4-rs` / bindings GNOME. - [ ] `serde` / `serde_json` pour contrats JSON. - [ ] Client HTTP Rust (`reqwest` ou équivalent). - [ ] WebSocket/SSE Rust selon choix backend. - [ ] `keyring` pour stockage token local. - [ ] `directories` pour config/cache. - [ ] `tracing` pour logs app. - [ ] Tokens `design_system/tokens/tokens.gnome.css`. - [ ] Backend `system_update` comme source de vérité. ## 12. URLs utiles - Rust : https://www.rust-lang.org/ - Rust Book : https://doc.rust-lang.org/book/ - GTK Rust bindings : https://www.gtk.org/docs/language-bindings/rust/ - gtk4-rs book : https://gtk-rs.org/gtk4-rs/stable/latest/book/ - libadwaita Rust : https://gtk-rs.org/gtk4-rs/stable/latest/book/libadwaita.html - GNOME Human Interface Guidelines : https://developer.gnome.org/hig/ - reqwest : https://docs.rs/reqwest/ - serde : https://serde.rs/ - keyring crate : https://docs.rs/keyring/ - Flatpak docs : https://docs.flatpak.org/ ## 13. Liens parent/enfant avec les autres tâches - Parents : - `tache5.md` pour API/capabilities/events. - `tache1.9.md` pour `api_clients`. - `tache3.md` pour reprise UX/tuiles. - `tache7.md` pour sécurité token/cache/metrics. - `design_system/tokens/tokens.gnome.css` pour thème natif. - Enfants : - aucune tâche enfant immédiate ; c'est une évolution future après webapp serveur stable. - Validation : `validation_tache8.md`.