diff --git a/.gitignore b/.gitignore index fbd5246..1cf45aa 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ reports/* # Dépôts de référence (git imbriqués) — inspiration uniquement, gérés séparément linux-update-dashboard/ nas-ops/ + +# Clé de session dev (jamais commitée) +.dev-session-key.txt diff --git a/amelioration.md b/amelioration.md new file mode 100644 index 0000000..6c08a9f --- /dev/null +++ b/amelioration.md @@ -0,0 +1,2 @@ +- dans l onglet terminal, il n y a pas de separation franche entre 2 machines distincte ou totalement separe? +- dans le champ host on peut mettre ip ou nostname .local ou .home ? \ No newline at end of file diff --git a/tache2.md b/tache2.md new file mode 100644 index 0000000..3a9ed6b --- /dev/null +++ b/tache2.md @@ -0,0 +1,139 @@ +# 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). diff --git a/validation_tache2.md b/validation_tache2.md new file mode 100644 index 0000000..133ac74 --- /dev/null +++ b/validation_tache2.md @@ -0,0 +1,93 @@ +# Protocole de validation — Tâche 2 (moteur de templates de mise à jour) + +> **Type** : grille de validation. Utilisée par l'agent orchestrateur (Claude Code principal) **après** qu'un agent sous-traitant a rendu la mission décrite dans `tache2.md`. +> **But** : vérifier que les livrables de la tâche 2 sont complets, respectent le périmètre, et **s'intègrent correctement à l'application existante** sans rien casser. +> **⚠️ Gate obligatoire** : cette validation doit être **passée AVANT toute phase de développement**. Tant que le verdict n'est pas ✅ Accepté, **aucune implémentation des livrables de la tâche 2 ne démarre** (ni par l'agent sous-traitant, ni par l'orchestrateur). Le design est figé et validé d'abord ; le code vient après. +> **Rappel** : la tâche 2 est une mission de **design/investigation** (pas d'implémentation). On valide donc des **documents de design/spec**, pas du code de production. Les vérifications de non-régression servent uniquement à confirmer que l'existant n'a pas été touché. + +--- + +## 0. Quand lancer cette validation +- La mission `tache2.md` est annoncée terminée. +- Le fichier `tache2.md` a bien été mis à jour avec sa section « État d'avancement / Ce qui a été fait » (clôture obligatoire). +- Les livrables de design sont présents sous `docs/` (ou l'emplacement proposé par l'agent). + +Si l'un de ces points manque → **rejet immédiat**, renvoyer à l'agent. + +--- + +## 1. Discipline & périmètre (l'agent n'a pas débordé) +Vérifier via `git status` / `git diff` et lecture des commits : +- [ ] **Aucun code de production modifié ou ajouté** : pas de changement sous `server/`, `client/`, `shared/`, `templates/`, ni dans les configs (`package.json`, `tsup.config.ts`, `vite.config.ts`, etc.). Seuls des fichiers `docs/**` et `tache2.md` doivent avoir changé. +- [ ] **Jalon 1 et jalon 2 intacts** : aucun fichier de ces jalons touché. +- [ ] Aucun autre chantier démarré hors du périmètre de `tache2.md` (les idées hors-scope doivent figurer comme *suggestions*, pas comme du travail réalisé). +- [ ] Les dépôts de référence (`linux-update-dashboard/`, `nas-ops/`) n'ont pas été copiés tels quels dans le code (respect licence AGPL). + +> Si du code de production a été écrit → **rejet** : la mission devait s'arrêter au design. + +--- + +## 2. Complétude des livrables +Confronter au § « Livrables attendus » et aux 5 axes de `tache2.md` : + +**Axes couverts :** +- [ ] Axe A — Templates APT (update, upgrade, full-upgrade, dist-upgrade, clean, autoremove, reboot) avec sémantique clarifiée et **profils OS** (Debian/Ubuntu/Proxmox/RPi) + gestion proxy apt-cacher-ng. +- [ ] Axe B — Capture des updates **prévus** (snapshot) et **appliqués** (diff avant/après), consommable par Hermes (déduplication + réduction). +- [ ] Axe C — Taxonomie des erreurs + stratégie de gestion/remédiation. +- [ ] Axe D — Docker : scan, pull, up, down, **prune images inutilisées**, détection des stacks (labels + fallback répertoires déclarés), JSON compact. +- [ ] Axe E — Scripts personnalisés (post-install, install paquets) + overrides par machine + garde-fous. + +**Livrables (§4 de tache2.md) :** +- [ ] Inventaire des templates. +- [ ] Contenu proposé des templates clés (pseudo-shell réaliste, convention `===SU:XXX===`). +- [ ] Schémas JSON canoniques étendus (snapshot + résultat, APT + Docker + erreurs + custom). +- [ ] Taxonomie des erreurs. +- [ ] Modèle des profils OS + overrides. +- [ ] Modèle des scripts personnalisés. +- [ ] Note de sécurité. +- [ ] Découpage en sous-jalons priorisé. + +**Questions d'investigation (§3) :** +- [ ] Les 7 questions sont tranchées, chacune avec MVP recommandé / alternatives / risques. + +> Tout livrable ou question manquant → **renvoi pour complément**. + +--- + +## 3. Cohérence & intégration avec l'application existante +C'est le cœur de la validation : le design doit **s'emboîter** avec ce qui existe. + +- [ ] **Types JSON** : les extensions proposées sont compatibles avec `shared/types.ts` (`UpdateSnapshot`, `ExecutionResult`). Les ajouts sont **rétro-compatibles** (champs optionnels, pas de rupture du jalon 1). Vérifier qu'un snapshot/exécution du jalon 1 resterait valide. +- [ ] **Convention des templates** : les templates proposés suivent la convention existante (marqueurs `===SU:XXX===`, `LC_ALL=C`, exécution sous `sudo -S`, sortie parsable). Cohérent avec `templates/apt/*.tpl`, `server/templates/render.ts`, `server/services/aptParse.ts`. +- [ ] **Parsing** : la stratégie retenue (JSON-in-shell vs parsing-TS) est explicite, justifiée, et compatible avec `server/services/` ou propose une migration claire sans casser le refresh/upgrade actuels. +- [ ] **Couche SSH** : le design réutilise `server/ssh/client.ts` (pas de nouveau mécanisme d'exécution non justifié) ; opérations longues/détachées traitées de façon cohérente. +- [ ] **Frontière Hermes/MCP** : aucun secret n'atteint Hermes/MCP ; la surface MCP reste minimale ; les données envoyées au LLM passent par la réduction déterministe (`aptReduce.ts` ou équivalent étendu). +- [ ] **Sécurité** : actions destructives (prune, down, reboot, dist-upgrade) exigent une validation explicite côté webapp ; pas de secret en clair (logs/UI/MCP). +- [ ] **Profils OS** : le mécanisme proposé n'invalide pas le comportement Debian/Ubuntu prouvé en prod au jalon 1. +- [ ] **Découpage en sous-jalons** : chaque sous-jalon est implémentable indépendamment et produit un logiciel testable (compatible avec le workflow spec → plan → implémentation). + +--- + +## 4. Non-régression (l'existant tourne toujours) +Confirmer que rien n'a été cassé (puisque la mission ne devait pas toucher le code) : +- [ ] `rtk pnpm check` → 0 erreur TypeScript. +- [ ] `rtk pnpm test` → suite verte (au moins les tests du jalon 1, + jalon 2 s'il est mergé). +- [ ] `rtk pnpm build` → `dist/index.js` + `dist/client` produits. +- [ ] Les flux prouvés du jalon 1 (ajout machine, refresh APT, full-upgrade, reboot, rapport) restent inchangés dans le code. + +> Une régression ici signifie que l'agent a touché au code malgré la consigne → **rejet**. + +--- + +## 5. Verdict +Rédiger une conclusion explicite : +- **✅ Accepté** : tous les blocs cochés. → On peut enchaîner sur `writing-plans` pour le 1ᵉʳ sous-jalon recommandé. +- **🟡 Accepté avec réserves** : livrables complets mais points de design à ajuster → lister les corrections, renvoyer pour itération courte. +- **❌ Rejeté** : périmètre débordé, code de production écrit, livrables incomplets, ou incohérence majeure avec l'appli → renvoyer à l'agent avec les points bloquants précis. + +Consigner le verdict (date, blocs en échec, actions de suite) en bas de ce fichier ou dans un commit dédié. + +--- + +## 6. Notes de validation (à remplir au moment de la revue) +> _(Section laissée vide ; à compléter lors de la validation effective : date, verdict, points relevés, décisions.)_