system_update/tache2.md

Consigne de dev — Moteur de templates de mise à jour (investigation & brainstorming)

Type : mission d'investigation + brainstorming + design (PAS d'implémentation). Destinataire : un agent de développement autonome (Claude Code ou équivalent), sans contexte préalable du projet. Langue : français. Livrable final attendu : un (ou plusieurs) document(s) de design/spec prêts à passer en plan d'implémentation — pas de code de production à ce stade.

---

0. Comment aborder cette mission

Tu travailles dans le dépôt system_update. Commence par lire ces fichiers (ils contiennent tout le contexte) :

• CLAUDE.md — règles du projet (sécurité, langue, architecture, rôle d'Hermes/MCP).
• deep-research-report(7).md — étude d'architecture (contrats JSON canoniques, flux, sémantique APT/Docker, réduction déterministe pour LLM).
• docs/superpowers/specs/2026-06-04-jalon1-tranche-verticale-apt-design.md — ce qui est déjà construit (jalon 1).
• ajout.md — périmètre du volet Hermes et du serveur MCP.
• Code existant à étudier (le jalon 1 est en prod, validé sur Debian + Ubuntu réels) :
  • templates/apt/ — check.sh.tpl, full-upgrade.sh.tpl, reboot.sh.tpl (convention actuelle des templates).
  • server/templates/render.ts (rendu Mustache), server/templates/aptReduce.ts (réducteur de lignes).
  • server/services/aptParse.ts (parsing de la sortie APT), server/services/refresh.ts, server/services/execute.ts.
  • server/ssh/client.ts (exécution SSH : sudo -S, script en base64, streaming).
  • shared/types.ts (types JSON canoniques UpdateSnapshot, ExecutionResult).
• Dépôts de référence (lecture seule, inspiration et non copie — vérifier les licences, linux-update-dashboard est en AGPL-3.0) :
  • nas-ops/ — scripts Bash JSON-friendly : nas-system-update, nas-system-upgrade, nas-docker-pull, nas-docker-up, nas-docker-prune. La meilleure référence pour cette mission.
  • linux-update-dashboard/ — orchestration web SSH multi-machines.

Méthode imposée : utilise le workflow superpowers — brainstorming (explorer, poser des questions une à une), puis writing-plans plus tard. Ici, arrête-toi au design/spec validé. Ne code pas le moteur final dans cette mission.

⛔ Périmètre strict — ne pas déborder

Tu travailles exclusivement sur cette tâche 2 (le design du moteur de templates décrit ici).

• N'implémente pas le code de production, ne refactore pas l'existant, ne touche pas au jalon 1 ni au jalon 2 (polish design system) en cours.
• Ne démarre aucun autre chantier non listé dans ce document, même s'il te paraît utile : note-le comme suggestion dans tes livrables, mais ne l'exécute pas.
• Si une question dépasse le cadre de la tâche 2, liste-la et arrête-toi plutôt que d'élargir le périmètre.
• En cas de doute sur le périmètre, demande plutôt que de présumer.

📝 Clôture obligatoire

À la fin de ta mission, mets à jour ce fichier tache2.md : ajoute une section « État d'avancement / Ce qui a été fait » en bas, récapitulant — les livrables produits (avec chemins), les décisions prises, les questions tranchées, ce qui reste ouvert, et les sous-jalons recommandés. Ce fichier doit refléter l'état réel de la mission une fois terminée.

---

1. Contexte produit (résumé)

Webapp de mise à jour distante de machines Linux (Debian, Ubuntu, Proxmox, Raspberry Pi OS) + Docker Compose, pilotée par SSH agentless. Le jalon 1 a prouvé l'ossature sur un cas minimal : ajout machine → refresh APT → tuile → full-upgrade/reboot avec terminal live → rapport Markdown archivé.

Principe directeur : la logique métier « comment mettre à jour » vit dans des templates shell versionnés sur disque (esprit nas-ops), rendus en Mustache et poussés en SSH. Le backend orchestre, parse les sorties en JSON canonique, archive logs + rapports. Hermes (copilote IA, via serveur MCP) analyse les JSON mais n'exécute jamais de SSH et ne reçoit jamais de secret.

Conventions techniques actuelles à respecter / questionner :

• Les templates émettent des marqueurs de section ===SU:XXX=== ; le backend extrait les sections et parse en TS (aptParse.ts).
• Exécution : LC_ALL=C, DEBIAN_FRONTEND=noninteractive, script entier lancé sous sudo -S (mot de passe sur stdin), encodé base64 pour éviter le quoting.
• Réduction déterministe des logs avant tout envoi à un LLM (aptReduce.ts : ne garde que Inst/Conf/Remv/Err/E:/W:/dpkg:/reboot-required).
• Deux messages JSON canoniques : snapshot de disponibilité (ce qui sera appliqué) et résultat d'exécution (ce qui a été appliqué). Voir shared/types.ts et le rapport.

---

2. Objectif de la mission

Concevoir (investigation + design, pas implémentation) le moteur de templates de mise à jour complet et les contrats de données associés, couvrant cinq axes :

Axe A — Templates APT complets et OS-aware

Concevoir l'inventaire et le contenu des templates pour : update (refresh index, déjà partiellement là), upgrade, full-upgrade, dist-upgrade, clean, autoremove, plus reboot/reboot-check.

• Clarifier la sémantique exacte de chaque commande (s'appuyer sur le manpage APT cité dans le rapport) : upgrade n'enlève/installe pas de paquets, dist-upgrade/full-upgrade gèrent les changements de dépendances, clean vide le cache, autoremove retire les dépendances inutiles.
• Profils par OS : Debian, Ubuntu, Proxmox (apt update puis apt dist-upgrade, dépôts pve), Raspberry Pi OS. Le moteur doit être profile-aware, pas du collage de commandes. Proposer un mécanisme de profils + overrides par machine.
• Gérer le proxy APT (apt-cacher-ng) : modes direct / temporaire à l'exécution / persistant dans /etc/apt/apt.conf.d/.

Axe B — Capture des mises à jour prévues et appliquées (pour Hermes)

• Avant : produire le snapshot des updates disponibles (paquets, versions courante→cible, origine, reboot requis). Déjà amorcé pour full-upgrade simulé ; étendre et fiabiliser.
• Après : produire un résultat d'exécution avec le diff réel avant/après (paquets effectivement modifiés, versions finales, erreurs résiduelles, reboot requis après coup).
• Définir comment ces données alimentent Hermes : déduplication par empreinte fonctionnelle (os_family + package + from + to + origin), lignes importantes seulement, log brut archivé à part. Réfléchir au format consommable par le serveur MCP.

Axe C — Gestion des erreurs

• Taxonomie des erreurs APT/dpkg : lock occupé, dépôt injoignable, conflit de paquets, dpkg --configure -a requis, espace disque, clé GPG, etc.
• Stratégie : codes de sortie normalisés, capture des lignes d'erreur pertinentes, statut ok|warning|error, conseils de remédiation (sans auto-réparation dangereuse non validée).
• Robustesse : idempotence, reprise, opérations longues qui survivent à une coupure SSH (le jalon 1 prévoyait nohup + fichier exit-code — à généraliser ou non, à trancher).

Axe D — Docker Compose

Concevoir les templates/contrats pour : scan des stacks Compose, pull, up -d (avec --remove-orphans), down, prune des images inutilisées (docker image prune / system prune, en distinguant le sûr du destructif).

• Détection des stacks : via labels des conteneurs en cours (com.docker.compose.project.working_dir, comme nas-ops) et fallback par scan des répertoires Compose déclarés depuis le frontend (stacks non démarrées).
• Détection des updates d'image : comparer les IDs/digests avant/après pull ; lire les labels de version/source quand ils existent. JSON compact listant uniquement les conteneurs réellement concernés.
• Étendre les schémas JSON canoniques au volet docker (le rapport en donne un exemple).
• Sécurité du prune : exiger une validation explicite côté webapp (action destructive).

Axe E — Scripts personnalisés (post-install, installation de paquets)

• Modèle pour des scripts custom versionnés : installation de paquets ad hoc, hooks post-install, configuration réseau, etc.
• Overrides par machine, variables de contexte, prévisualisation avant exécution (preview_template).
• Garde-fous : validation opérateur, pas de secret dans les scripts, traçabilité (rapport + log).

---

3. Questions d'investigation à trancher

Produire des réponses argumentées (MVP recommandé / alternatives / risques) pour :

1. JSON-in-shell vs parsing-in-TS : nas-ops produit le JSON dans le script ; le jalon 1 parse en TS. Quelle stratégie pour la suite ? (cohérence, testabilité, robustesse multi-OS). Trancher et justifier.
2. Structure des profils OS : fichiers de templates par profil ? héritage/override ? convention de nommage et d'arborescence sous templates/.
3. Capture avant/après : comment obtenir un diff fiable des paquets réellement appliqués (parser apt-get ? interroger dpkg ? snapshot dpkg avant/après ?).
4. Contrats JSON : quelles extensions exactes à UpdateSnapshot et ExecutionResult (shared/types.ts) pour Docker, erreurs, scripts custom ? Proposer les types.
5. Idempotence & opérations longues : généraliser l'exécution détachée (nohup + exit-code) ? Comment suivre la progression et reprendre ?
6. Sécurité Docker prune / scripts custom : où placer la barrière de validation, comment éviter toute fuite de secret vers Hermes/MCP.
7. Surface MCP : quels nouveaux outils/contrats exposer à Hermes pour ces capacités (cf. list_templates, preview_template, run_action…), en gardant la surface minimale.

---

4. Livrables attendus de cette mission

À produire sous docs/ (proposer l'emplacement), en français :

1. Inventaire des templates (APT + Docker + custom) : nom, rôle, OS ciblés, variables, marqueurs de sortie, sémantique.
2. Contenu proposé des templates clés (au moins en pseudo-shell réaliste), cohérent avec la convention ===SU:XXX=== existante.
3. Schémas JSON canoniques étendus (snapshot + résultat) couvrant APT, Docker, erreurs, scripts custom — avec règles de déduplication et de réduction pour Hermes.
4. Taxonomie des erreurs + stratégie de gestion et de remédiation.
5. Modèle des profils OS et des overrides par machine.
6. Modèle des scripts personnalisés (post-install, install paquets) avec garde-fous.
7. Note de sécurité : ce qui ne doit jamais atteindre Hermes/MCP, validations requises pour les actions destructives.
8. Découpage en sous-jalons implémentables indépendamment (chacun = un cycle spec → plan → implémentation), avec ordre recommandé.

---

5. Contraintes (non négociables)

• Sécurité : aucun secret (mot de passe, sudo, token, clé) ne transite vers Hermes/MCP ni dans un prompt LLM ; jamais de secret en clair dans logs/UI/retours. Actions destructives (prune, down, reboot, dist-upgrade) → validation explicite côté webapp.
• Réduction déterministe avant tout appel LLM ; log brut complet archivé séparément.
• Templates versionnés sur disque (éditables depuis le frontend mais sauvegardés comme ressources de projet, revues Git) ; pas de commandes critiques uniquement en base.
• OS profile-aware ; ne pas casser le jalon 1 existant (Debian/Ubuntu refresh + full-upgrade + reboot fonctionnent en prod).
• Esprit du projet : le backend orchestre, les scripts shell portent la logique métier, le JSON canonique est le langage commun frontend/MCP/Hermes.
• Rester dans une surface MCP minimale et des fichiers à responsabilité unique.

---

6. Définition de « terminé » pour cette mission

• Tous les axes A→E couverts par un design argumenté.
• Les 7 questions d'investigation tranchées (MVP/alternatives/risques).
• Les livrables de la §4 rédigés et cohérents entre eux.
• Un découpage en sous-jalons priorisé, prêt à passer en writing-plans.
• Aucune implémentation de production livrée (cette mission s'arrête au design validé).
• Le fichier tache2.md mis à jour avec la section « État d'avancement / Ce qui a été fait » (cf. clôture obligatoire ci-dessus).

Étape suivante (hors de cette mission) : tes livrables seront passés au crible de validation_tache2.md (grille de validation + gate). Aucune phase de développement ne démarre tant que ce gate n'est pas ✅ Accepté. Conçois donc tes livrables pour qu'ils soient vérifiables contre cette grille (complétude, périmètre respecté, cohérence et intégration avec l'appli existante, non-régression).