# 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.
4. Mettre en place un **processus de backup** de la v1 avant modification.

**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.