Files

T

gilles 0fbca06d3d docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation

Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-05 19:50:25 +02:00

13 KiB

Raw Blame History

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

┌──────────────────────────────────────────────┐
│ 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 :

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 :

{
  "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

┌────────────────────────────────────────────────────────────────────┐
│ 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

┌────────────────────────────────────────────────────────────────────┐
│ 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

┌────────────────────────────────────────────────────────────────────┐
│ 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/ :

Architecture app locale ↔ backend.
Choix stack Rust/GNOME argumenté.
Contrat API nécessaire.
Modèle de sécurité/token.
Mapping design system web → GNOME.
Maquettes ASCII vues principales.
Plan de cache/offline lecture seule.
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.

13 KiB Raw Blame History