pilot/prompt_codex_v_2.md

# Prompt Codex — PILOT v2 (Rust) : refonte + déploiement Linux/Windows

## 0) Rôle et livrables attendus

Tu es **Codex**, agent de refonte et d’industrialisation. Tu dois :

1. **Analyser** le projet existant (PILOT v1) et produire un état des lieux.
2. Concevoir puis générer **PILOT v2** en **Rust**, avec **deux builds** (Linux et Windows) partageant un **contrat MQTT commun**, mais pouvant utiliser des implémentations différentes.
3. Produire une **documentation complète** : plan, tests, TODO, changelog, notice déploiement et notice d’utilisation, stucture du projet, explication des flux mqtt en mermaid (telemetry, commandes, ....)
4. Mettre en place un **processus de backup** de la v1 avant modification.
5. ajouter un commentaire en tete de chaque fichier pour expliquer son role, lisible par un novice en Rust.
6. pas de timestamps dans les fichiers sauf demande explicite.
7. afficher un estimatif du taux de developpement de l'app en fin de chaque message.
**Sorties obligatoires (fichiers)**

- `docs/analyse_v1.md`
- `docs/architecture_v2.md`
- `docs/planning_v2.md`
- `docs/todo_v2.md`
- `CHANGELOG.md`
- `docs/deploiement.md`
- `docs/utilisation.md`
- `config/config.example.yaml`
- `README.md` (mis à jour)
- (code) `pilot-v2/` avec structure Rust + workspace si nécessaire

---

## 1) Objectifs fonctionnels de l’application

L’application “pilot” expose via **MQTT** (Home Assistant autodiscovery) :

- **Télémetrie PC** : CPU usage, température, fréquence (lecture), RAM, IP, batterie/charge, GPU (si dispo).
- **États système** : `power_state` : `on|off|sleep|hibernate|locked|unknown` (au minimum on/sleep/off à implémenter).
- **Commandes** : shutdown, reboot, sleep (veille) ; écran on/off.
- **Home Assistant** : publication discovery + availability + states.
- **Robustesse** : reconnexion MQTT, LWT, cadence de publish, cache des valeurs.

### Contraintes et décisions

- **Config** : YAML (obligatoire).
- **Sécurité avancée (signature/HMAC)** : **plus tard** → à mettre dans TODO.
- **Écran** : proposer **2 technos** sélectionnables par paramètre (par OS).
- **Deux versions** : Linux et Windows (pas forcément mêmes technos internes), mais **même schéma MQTT**.
- **Technologie choisie** : **Rust** (déploiement binaire, robustesse).
- **Bonnes pratiques Rust** : modules clairs, `clippy`, `fmt`, logs `tracing`, erreurs `thiserror/anyhow`, configuration `serde_yaml`, code async si MQTT async.

---

## 2) Étape 1 — Backup obligatoire de la v1

Avant toute modification :

- Créer un dossier `backup_v1/<YYYYMMDD_HHMM>/` à la racine.
- Copier **l’intégralité** du projet v1 dans ce dossier (sans exclure).
- Générer `backup_v1/<...>/manifest.txt` :
  - hash (sha256) des fichiers
  - liste arborescence
  - note de version (si trouvée)

Aucun fichier v1 ne doit être détruit.

---

## 3) Étape 2 — Analyse v1 (à produire dans docs/analyse\_v1.md)

- Décrire : objectifs, techno, scripts, modules, service systemd, dépendances.
- Lister topics MQTT existants, discovery, states, commands.
- Recenser commandes système utilisées (shutdown/reboot/screen/cpu freq).
- Identifier points faibles (sécurité, duplication, config hardcodée, absence LWT).
- Proposer une synthèse “ce que v2 doit corriger”.

---

## 4) Spécification v2 (contrat MQTT + config YAML)

### 4.1 Schéma MQTT (stable)

Définir un schéma **unique** (à documenter dans `docs/architecture_v2.md`) :

- Base topic : `pilot/<device>/...`
- `availability` : online/offline (LWT recommandé)
- `status` : JSON (version, os, uptime, last\_error, backends)
- `capabilities` : JSON (features réellement actives)
- `state/<name>` : états capteurs/états système
- `cmd/<action>/set` : commandes

Décider QoS / retain :

- discovery: retain=true, qos=1
- states: retain configurable (défaut true)
- commands: retain=false

### 4.2 Configuration YAML (obligatoire)

Créer `config/config.example.yaml` et implémenter lecture depuis :

- Linux : `/etc/pilot/config.yaml` puis fallback `./config.yaml`
- Windows : `C:\ProgramData\Pilot\config.yaml` puis fallback `./config.yaml`

Le YAML doit inclure :

- device (name, identifiers)
- mqtt (host, port, creds, base\_topic, discovery\_prefix, client\_id)
- features (telemetry, commands)
- power backend (linux\_logind\_polkit | linux\_sudoers | windows\_service)
- screen backend (Linux: gnome\_busctl | x11\_xset ; Windows: winapi\_session | external\_tool)
- publish cadence (heartbeat, intervals)
- cooldown commandes

---

## 5) Architecture code Rust (séparation Linux/Windows)

Créer un dossier `pilot-v2/` (Rust) avec cette structure minimale :

```
pilot-v2/
  Cargo.toml
  src/
    main.rs
    lib.rs
    config/
    mqtt/
    ha/
    telemetry/
    commands/
    platform/
      linux/
      windows/
    runtime/
    security/
  docs/ (optionnel si tu préfères à la racine)
```

### Principes d’implémentation

- Définir des `trait` internes (PowerControl, ScreenControl, TelemetryProvider).
- `platform/linux/*` implémente Linux.
- `platform/windows/*` implémente Windows.
- Factory sélectionne backends selon YAML et publie `capabilities`.
- Gestion erreurs : `thiserror` + `anyhow` (ou uniquement `anyhow`).
- Logs : `tracing` (niveau configurable).
- Format : `cargo fmt`, qualité : `cargo clippy` sans warnings.

### Dépendances Rust recommandées (à valider par Codex)

- MQTT : `rumqttc`
- YAML : `serde`, `serde_yaml`
- CLI : `clap` (optionnel mais recommandé)
- Logs : `tracing`, `tracing-subscriber`
- Erreurs : `anyhow`, `thiserror`
- Temps/scheduling : `tokio` (si async), sinon scheduler maison

---

## 6) Déploiement (Linux + Windows)

### Linux

- Produire un binaire `pilot`.
- Fournir un service systemd `pilot.service` (user dédié `pilot` recommandé).
- Support backend power via logind/polkit (recommandé) OU sudoers (fallback).
- Documenter installation, configuration, démarrage, logs (`journalctl -u pilot`).

### Windows

- Produire un binaire `pilot.exe`.
- Déploiement minimal : exécutable + config + tâche planifiée OU service Windows.
- Pour écran : prévoir limitation “service vs session”, et proposer backend `winapi_session` ou `external_tool`.

---

## 7) Planning + Tests

### 7.1 Planning (docs/planning\_v2.md)

Inclure un plan par phases :

1. Backup + analyse v1
2. Spéc contract MQTT + YAML
3. Squelette Rust + MQTT connect + LWT + status/capabilities
4. Telemetry de base (cpu/mem/net)
5. Commandes power (shutdown/reboot/sleep)
6. Écran (2 backends par OS)
7. Home Assistant discovery
8. Packaging + services (systemd / windows)
9. Tests + release

### 7.2 Tests (à implémenter au minimum)

- Unit tests : parsing YAML + validation
- Unit tests : parsing commandes MQTT payload + cooldown
- “Dry-run mode” : exécute sans faire shutdown/reboot, mais log l’action
- Test manuel documenté : checklist HA (entités visibles, commandes ok)

---

## 8) TODO + CHANGELOG

- `docs/todo_v2.md` : liste items P0/P1/P2
  - inclure : sécurité avancée (HMAC), TLS, ACL, signature
  - inclure : amélioration power\_state (hibernate/locked), GPU multi-vendors
- `CHANGELOG.md` : format Keep a Changelog, version 2.0.0 initiale

---

## 9) Notices à produire

### docs/deploiement.md

- Pré-requis
- Installation Linux (binaire, config, service)
- Installation Windows (binaire, config, tâche/service)
- Upgrade / rollback (revenir v1 via dossier backup)
- Debug (logs, topics MQTT, health)

### docs/utilisation.md

- Entités HA attendues
- Commandes (shutdown/reboot/sleep/screen)
- Power state (interprétation)
- Paramètres YAML courants
- Dépannage rapide

---

## 10) Exigences de qualité

- Ne pas casser v1 : tout nouveau code dans `pilot-v2/`.
- Le contrat MQTT doit être **documenté** et stable.
- L’agent doit publier `status` + `capabilities`.
- L’agent doit fonctionner même si certaines features sont indisponibles (désactiver et expliquer via logs/status).
- Pas de promesses “Windows complet” si non implémenté : publier capabilities réelles.

---

## 11) Première action à exécuter maintenant

1. Générer le backup v1
2. Générer `docs/analyse_v1.md`
3. Proposer l’arborescence Rust + `config/config.example.yaml`
4. Proposer le contrat MQTT final (dans `docs/architecture_v2.md`) Ensuite seulement : commencer l’implémentation.

Fin.