gilles/system_update
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08919752e3f1a21161ab98558411335c5b88649c
system_update/tache2.md
T
gilles 0fbca06d3d docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation 
Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-05 19:50:25 +02:00

20 KiB
Raw Blame History

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.
  • Profils par type de machine : distinguer machine physique, VM, hôte Proxmox, LXC/container, Raspberry Pi, serveur GPU/workstation. Ce type influence les scripts proposés : firmware, drivers, benchmark, reboot, outils Proxmox, détection hardware.
  • Gérer le proxy APT (apt-cacher-ng) : modes direct / temporaire à l'exécution / persistant dans /etc/apt/apt.conf.d/.

Spécificités à intégrer :

  • Debian récent : vérifier les composants APT nécessaires (main, contrib, non-free, non-free-firmware) avant de proposer firmware/drivers propriétaires ;
  • Ubuntu : prévoir ubuntu-drivers pour analyse/proposition drivers, surtout NVIDIA/GPU ;
  • Proxmox : utiliser le profil Proxmox dédié, ne pas le traiter comme une Debian générique ; contrôler dépôts PVE, meta-package proxmox-ve, kernel PVE, éventuel Ceph, puis apt-get dist-upgrade ;
  • Raspberry Pi OS : profil dédié, attention firmware/kernel, espace disque avant upgrade, usage de full-upgrade ;
  • VM : privilégier outils invités (qemu-guest-agent, open-vm-tools selon hyperviseur), éviter drivers GPU/firmware non pertinents sauf passthrough ;
  • machine physique : proposer détection hardware, firmware, SMART/disques, sensors, drivers GPU et benchmarks.

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. Structure des profils machine : choix manuel à l'ajout vs détection automatique (systemd-detect-virt, /etc/os-release, dmidecode, lspci, /proc/cpuinfo) ; règles de correction utilisateur.
  4. 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 ?).
  5. Contrats JSON : quelles extensions exactes à UpdateSnapshot et ExecutionResult (shared/types.ts) pour Docker, erreurs, scripts custom, hardware et métriques ? Proposer les types.
  6. Idempotence & opérations longues : généraliser l'exécution détachée (nohup + exit-code) ? Comment suivre la progression et reprendre ?
  7. Sécurité Docker prune / scripts custom : où placer la barrière de validation, comment éviter toute fuite de secret vers Hermes/MCP.
  8. 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 profils machine : physique, VM, hôte Proxmox, LXC, Raspberry Pi, serveur GPU, workstation.
  7. Modèle des scripts personnalisés (post-install, install paquets, hardware, drivers, métriques) avec garde-fous.
  8. Note de sécurité : ce qui ne doit jamais atteindre Hermes/MCP, validations requises pour les actions destructives.
  9. 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 8 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).

7. Technos à utiliser — checklist

  • Bash POSIX-ish pour templates shell, avec LC_ALL=C.
  • Mustache pour rendu de templates.
  • TypeScript pour parsing, réduction et contrats JSON.
  • apt-get en scripts, pas apt interactif.
  • dpkg-query pour diff avant/après.
  • Docker CLI + Docker Compose plugin pour stacks.
  • SSH existant server/ssh/client.ts, sudo -S, base64 script.
  • Réduction déterministe avant Hermes/MCP.
  • Logs bruts archivés séparément des JSON.

8. URLs utiles

9. Liens parent/enfant avec les autres tâches

  • Parents :
    • tache1.9.md pour stockage et indexation.
  • Enfants :
    • tache4.md pour scripts post-install détaillés.
    • tache5.md pour exécution backend, jobs et API.
    • tache3.md pour affichage des snapshots/actions.
    • tache6.md pour analyse Hermes des JSON.
    • tache7.md pour réduction tokens/nettoyage.
  • Validation : validation_tache2.md.

10. État d'avancement / Ce qui a été fait

Statut : mission de design terminée. Aucun code de production écrit (uniquement des .md sous docs/design/tache2/ + cette section). Aucun commit. Prêt à repasser le gate validation_tache2.md.

Livrables produits (chemins)

Tous sous docs/design/tache2/ :

  • 00-synthese.md — vue d'ensemble, cartographie des livrables, décisions structurantes, alignement tache1.9.md, hors-scope.
  • 10-templates-apt.md — sémantique APT clarifiée, inventaire des templates APT, variables Mustache, pseudo-shell réaliste (update-analyze/upgrade/full-upgrade/autoremove/clean/reboot), profils OS, migration non-régressive du jalon 1.
  • 20-docker.md — méthode Docker par SSH, inventaire + pseudo-shell des 6 templates docker/* (scan/inspect/pull-check/apply/prune/down), flux 1→8, réduction Hermes, insertion webapp.
  • 30-scripts-custom.md — modèle moteur post-install (manifestes, champs dynamiques, garde-fous), profils attendus, pseudo-shell des templates custom, renvoi catalogue détaillé à la tâche 4.
  • 40-contrats-json.md — schémas JSON canoniques étendus + types TypeScript rétro-compatibles (extensions de shared/types.ts), déduplication, réduction déterministe, mapping vers les tables tache1.9.md.
  • 50-erreurs.md — taxonomie des erreurs APT/dpkg/Docker/réseau + codes normalisés + remédiation + interactions humaines + idempotence/reprise.
  • 60-profils-os-machine.md — modèle profils OS (arborescence + fallback base), type machine, overrides par machine, machine_probe, proxy apt-cacher-ng (direct/runtime/persistent).
  • 70-securite.md — frontière Hermes/MCP, actions destructives + validations, surface MCP minimale, traçabilité.
  • 80-sous-jalons.md — découpage en 10 sous-jalons (SJ-0→SJ-9) priorisé, prêt pour writing-plans.
  • 90-questions-investigation.md — les 8 questions §3 tranchées (MVP/alternatives/risques).
  • 99-couverture-gate.md — auto-évaluation case par case de validation_tache2.md (§1→§8).

Décisions prises (résumé)

  1. Parsing hybride à dominante TS (marqueurs ===SU:XXX=== + TSV dpkg-query + docker --format json), rétro-compatible jalon 1.
  2. Profils OS = un fichier complet par profil sous templates/<osFamily>/, fallback base (Debian/Ubuntu inchangés).
  3. Type machine = choix manuel + machine_probe de correction (jamais auto-appliquée).
  4. Diff réel = snapshot dpkg before/after, l'exit code ne suffit jamais.
  5. Extensions de shared/types.ts = unions élargies + blocs optionnels (docker/errors/reboot/postInstall/champs apt), schemaVersion?. Payload jalon 1 reste valide.
  6. Opérations longues = nohup + exit-code pour les actions applicatives ; reboot vérifié via boot_id + délai adaptatif ; refresh synchrone.
  7. Sécurité = barrière action_requests côté webapp + nettoyage des secrets ; Hermes propose, ne déclenche jamais.
  8. Surface MCP = v1 conservée (8 outils), capacités nouvelles via run_action filtré ; aucune primitive SSH exposée.

8 questions d'investigation — tranchées

Q1 JSON-in-shell vs TS · Q2 structure profils OS · Q3 profils machine · Q4 capture avant/après · Q5 extensions JSON · Q6 idempotence/opérations longues · Q7 sécurité prune/scripts · Q8 surface MCP. Détail dans 90-questions-investigation.md.

Ce qui reste ouvert

  • Exécution pnpm check/test/build (non-régression §4) : à lancer par l'orchestrateur (aucun code touché ⇒ attendu vert).
  • Rendu UI fin des snapshots/actions : tâche 3 (le design pose les contrats/exigences).
  • Conflit délimiteurs Mustache vs Go-templates Docker ({{ }}) : choix à figer en implémentation (SJ-4).
  • Catalogue détaillé des scripts post-install : tâche 4 (mécanisme moteur posé ici).
  • File de jobs persistante / API d'action : tâche 5.

Sous-jalons recommandés (ordre)

SJ-0 socle types/réduction/résolution (bloquant) → SJ-1 APT update/analyse → SJ-2 APT upgrade + diff dpkg → SJ-3 reboot vérifié ; en parallèle SJ-4 Docker scan/inspect → SJ-5 pull-check → SJ-6 apply/prune/down ; transversal SJ-7 profils Proxmox/RPi + proxy persistent ; puis SJ-8 post-install bootstrap/identité → SJ-9 post-install Docker officiel/partages/VM tools. Détail dans 80-sous-jalons.md.

Reference in New Issue View Git Blame Copy Permalink