# 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

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

### 8.1 — Préparation sécurité client local

- [x] Définir le modèle `api_clients` côté backend.
- [x] Prévoir scopes : lecture seule, opérateur, admin, debug.
- [x] Prévoir révocation de token.
- [x] Documenter stockage token app locale via keyring.
- [x] Préparer un middleware d'auth API après validation du mode d'amorçage admin.
- [x] 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.
- [x] Ajouter `/api/system/status`.
- [x] Ajouter `/api/system/metrics`.

### 8.3 — Scaffold Rust/GNOME

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

### 8.4 — UI native MVP

- [x] Première fenêtre GTK/libadwaita derrière feature `gui`.
- [x] Champ URL serveur.
- [x] Boutons `Capabilities`, `Status`, `Metrics`.
- [x] 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

- [x] Le repo a été inspecté.
- [x] Le manque prioritaire est identifié : endpoint capabilities absent.
- [x] Patch API capabilities appliqué.
- [x] Vérification TypeScript passée.
- [x] Vérification Vitest ciblée passée.
- [x] 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

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

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

Puis retester :

```bash
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.