pilot/backup_v1/20251229_0205/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.
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.