# 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).