system_update/docs/design/tache2/00-synthese.md

Tâche 2 — Moteur de templates de mise à jour : synthèse de design

Type : document de design / spec. Aucune implémentation. Langue : français. Périmètre : design du moteur de templates (APT + Docker + scripts custom) et des contrats de données associés, prêt à passer en writing-plans. Statut : design figé proposé, à valider contre validation_tache2.md (gate obligatoire avant tout code).

---

1. Objet de la mission

Concevoir — sans coder — le moteur de templates de mise à jour complet et les contrats JSON associés, couvrant cinq axes :

• Axe A — Templates APT complets et OS-aware (update/analyse, upgrade, full/dist-upgrade, clean, autoremove, reboot-check, reboot vérifié), profils OS + type machine, proxy apt-cacher-ng.
• Axe B — Capture des mises à jour prévues (snapshot) et appliquées (diff réel avant/après), consommables par Hermes via déduplication + réduction déterministe.
• Axe C — Taxonomie des erreurs APT/dpkg/Docker + stratégie de remédiation.
• Axe D — Docker Compose : scan, inspect, pull-check, apply, prune, down, par SSH, avec racines déclarées + détection labels.
• Axe E — Scripts personnalisés (post-install, installation de paquets) avec garde-fous, manifestes et champs dynamiques.

La logique métier vit dans des templates shell versionnés sur disque (esprit nas-ops), rendus en Mustache et poussés en SSH (server/ssh/client.ts). Le backend orchestre, parse en JSON canonique, archive logs + rapports. Hermes analyse les JSON réduits, n'exécute jamais de SSH, ne reçoit jamais de secret.

---

2. Cartographie des livrables

Fichier	Contenu	Axe / Livrable §4
00-synthese.md (ce fichier)	Vue d'ensemble, décisions clés, couverture du gate	tous
10-templates-apt.md	Inventaire + pseudo-shell des templates APT, sémantique, marqueurs	A, §4.1, §4.2
20-docker.md	Inventaire + pseudo-shell Docker Compose, flux, sécurité prune/down	D, §4.1, §4.2
30-scripts-custom.md	Modèle des profils post-install, manifestes, champs dynamiques, garde-fous	E, §4.1, §4.7
40-contrats-json.md	Schémas JSON canoniques étendus + types TS rétro-compatibles + déduplication/réduction	B, §4.3
50-erreurs.md	Taxonomie des erreurs APT/dpkg/Docker/réseau + codes + remédiation	C, §4.4
60-profils-os-machine.md	Modèle profils OS + type machine + overrides + proxy APT + détection	A, §4.5, §4.6
70-securite.md	Frontière Hermes/MCP, actions destructives, validations, surface MCP	§4.8
80-sous-jalons.md	Découpage en sous-jalons priorisé, prêt pour writing-plans	§4.9
90-questions-investigation.md	Les 8 questions §3 tranchées (MVP / alternatives / risques)	§3
99-couverture-gate.md	Auto-évaluation case par case de validation_tache2.md	gate

---

3. Décisions structurantes (résumé)

Détail et justifications dans 90-questions-investigation.md. Synthèse :

1. Parsing : hybride, parsing-TS dominant (MVP). On conserve l'approche actuelle (marqueurs ===SU:XXX=== + parsing TS dans server/services/), enrichie par des données structurées en TSV/clé=valeur produites côté shell (ex. dpkg-query -W -f=..., docker ... --format json) là où le format est déjà stable et documenté. Pas de génération de gros JSON imbriqué dans le shell. Rétro-compatible avec le jalon 1.
2. Profils OS = fichiers de templates par profil + héritage par convention de dossier. Arborescence templates/<famille>/<commande>.sh.tpl avec un profil base et des overrides par OS résolus par ordre de priorité. Le moteur de rendu choisit le template le plus spécifique disponible (fallback vers base).
3. Type machine = choix manuel à l'ajout + action machine_probe de correction. L'opérateur choisit os_family et machine_kind au formulaire ; une sonde non destructive propose des corrections (jamais appliquées automatiquement sans validation).
4. Diff avant/après = snapshot dpkg autour de chaque action APT réelle. dpkg-query -W -f='${binary:Package}\t${Version}\t${Architecture}\n' avant et après ; le backend calcule le diff. L'exit code APT ne suffit jamais à déclarer un succès.
5. Extensions de shared/types.ts : tout en champs optionnels. Élargissement des unions (OsFamily, ActionType, AptProxyMode), ajout de blocs optionnels apt (détaillé), docker, custom/postInstall, reboot, errors sur UpdateSnapshot / ExecutionResult. Un snapshot/exécution du jalon 1 reste strictement valide.
6. Opérations longues : nohup + fichier exit-code généralisé pour les actions applicatives longues, mais pas pour le refresh. Reboot vérifié = mécanisme dédié (boot_id avant/après, reconnexion, délai adaptatif). Le refresh/analyse reste synchrone et court.
7. Sécurité prune/down/scripts : barrière de validation côté webapp + action_requests. Hermes propose, ne déclenche jamais. Secrets jamais lus ni renvoyés (registry creds, sudo, tokens). Erreurs nettoyées avant UI/MCP.
8. Surface MCP minimale, en lecture + déclenchement d'actions déjà autorisées. Réutilise les outils v1 du rapport (list_machines, get_machine_snapshot, get_machine_execution, list_templates, preview_template, run_refresh, run_action, search_reports) ; aucune nouvelle primitive d'exécution SSH exposée.

---

4. Principes invariants respectés

• Convention templates : tous les templates émettent des marqueurs ===SU:XXX=== ; LC_ALL=C ; DEBIAN_FRONTEND=noninteractive pour APT ; exécution sous sudo -S via runScriptSudo (base64) ; marqueur de sortie ===SU:EXIT=N===.
• Réduction déterministe avant LLM : le réducteur (aptReduce.ts, à étendre en reduceLines.ts) ne garde que les lignes utiles APT et Docker ; le log brut complet est archivé séparément (raw_artifacts / rawLogPath).
• Déduplication : APT par os_family + package + from + to + origin ; Docker par image + fromDigest + toDigest (fallback image + fromImageId + toImageId).
• Templates versionnés sur disque : éditables depuis le front mais sauvegardés comme ressources de projet (revues Git), versionnés via install_recipe_versions pour les scripts custom.
• Backend orchestre, shell porte la logique métier, JSON canonique = langage commun frontend / MCP / Hermes.
• Réutilisation de l'existant : pas de nouveau mécanisme d'exécution SSH ; on s'appuie sur runScriptSudo / runPlain et sur la table executions + WebSocket terminal.

---

5. Alignement avec tache1.9.md (schéma BDD cible)

Les contrats JSON et tables dérivées de ce design se rangent dans les tables prévues :

• Snapshot APT/Docker → snapshots(kind, payload_json, important_json) + tables dérivées apt_planned_packages, docker_compose_stacks, docker_stack_services.
• Résultats d'exécution → executions(result_json, important_json) + apt_applied_packages, docker_image_events, apt_errors.
• Scripts custom → install_profiles, install_recipes, install_recipe_versions, machine_profile_state, script_variables_presets.
• Messages importants extraits → important_messages.
• Config Docker par machine → docker_settings, docker_compose_roots.
• Profils OS / type machine → colonnes machines.os_family / machine_kind / virtualization / hardware_profile + machine_hardware (sonde).

Aucune table nouvelle n'est requise par la tâche 2 ; le design réutilise la cible tache1.9.md.

---

6. Ce qui reste hors périmètre (suggestions, pas exécuté)

• Catalogue détaillé des scripts post-install → renvoyé à tâche 4 (ce design pose le mécanisme moteur + les manifestes attendus).
• API/jobs/route d'action, file de jobs persistante → tâche 5.
• Affichage UI fin des snapshots/actions → tâche 3.
• Skill Hermes et analyse → tâche 6.
• Politique de rétention/purge des logs → tâche 7.
• Découverte réseau de machines → hors tâche 2.

Ces points sont mentionnés comme contexte d'emboîtement mais ne sont pas conçus en détail ici.