gilles
0fbca06d3d
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>
219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# Protocole de validation — Tâche 4 (scripts post-install et installateurs)
|
|
|
|
> **Type** : grille de validation. Utilisée après la mission décrite dans `tache4.md`.
|
|
> **But** : vérifier que les profils/scripts post-install sont complets, non interactifs, sûrs, versionnables et compatibles JSON.
|
|
> **Gate obligatoire** : cette validation doit être passée avant implémentation de nouveaux scripts.
|
|
> **Rappel** : la tâche 4 est une mission design scripts/contrats, pas d'implémentation.
|
|
|
|
---
|
|
|
|
## 0. Quand lancer cette validation
|
|
|
|
- La mission `tache4.md` est annoncée terminée.
|
|
- Le catalogue de profils/scripts est produit.
|
|
- Les JSON d'entrée/sortie sont spécifiés.
|
|
|
|
---
|
|
|
|
## 1. Discipline & périmètre
|
|
|
|
- [ ] Aucun script de production ajouté/modifié.
|
|
- [ ] Aucun `curl | sh` opaque validé sans justification.
|
|
- [ ] Aucun secret en clair dans variables, logs, rapports ou MCP.
|
|
- [ ] Les scripts sont prévus en templates versionnés sur disque.
|
|
- [ ] Tout script est non interactif.
|
|
|
|
---
|
|
|
|
## 2. Profils minimum
|
|
|
|
- [ ] `bootstrap_root`.
|
|
- [ ] `identity_network`.
|
|
- [ ] `base_tools` sans `vim`.
|
|
- [ ] `network_tools` avec `nmap` classé admin local contrôlé.
|
|
- [ ] `dev_git`.
|
|
- [ ] `sharing` avec Samba/NFS/mDNS/wsdd2.
|
|
- [ ] `docker_official`.
|
|
- [ ] `home_automation`.
|
|
- [ ] `dev_tools`.
|
|
- [ ] `embedded_esp_platformio`.
|
|
- [ ] `terminal_customization`.
|
|
|
|
---
|
|
|
|
## 3. Hardware, OS et métriques
|
|
|
|
- [ ] `machine_probe` spécifié.
|
|
- [ ] `machine_metrics_simple` spécifié.
|
|
- [ ] `apt_repositories` spécifié.
|
|
- [ ] `firmware_tools` spécifié.
|
|
- [ ] `gpu_drivers` spécifié.
|
|
- [ ] `benchmark_tools` spécifié.
|
|
- [ ] Les scripts dépendent du couple OS/type machine.
|
|
- [ ] Les drivers/firmware/benchmark ne sont pas installés par défaut.
|
|
|
|
---
|
|
|
|
## 4. Manifestes et champs UI
|
|
|
|
- [ ] Chaque profil possède id, label, description, risque, fields, defaults, validations.
|
|
- [ ] Cocher un profil déplie les champs obligatoires.
|
|
- [ ] Le bouton run reste désactivé si les champs requis sont invalides.
|
|
- [ ] Preview template prévue avec masquage secrets.
|
|
- [ ] Les décisions manquantes produisent `human_interaction_required`, pas un blocage SSH.
|
|
|
|
---
|
|
|
|
## 5. Cycle d'exécution
|
|
|
|
- [ ] `precheck`.
|
|
- [ ] `install`.
|
|
- [ ] `configure`.
|
|
- [ ] `initialize`.
|
|
- [ ] `verify`.
|
|
- [ ] `report JSON`.
|
|
- [ ] Les sauvegardes de fichiers système sont prévues avant modification.
|
|
- [ ] Reboot/reconnexion sont signalés et intégrés à `reboot_verified`.
|
|
|
|
---
|
|
|
|
## 6. JSON et erreurs
|
|
|
|
- [ ] JSON d'entrée défini.
|
|
- [ ] JSON résultat défini.
|
|
- [ ] Liste paquets/services/fichiers modifiés incluse.
|
|
- [ ] Taxonomie erreurs présente.
|
|
- [ ] Les logs bruts sont archivés, les lignes importantes réduites.
|
|
|
|
---
|
|
|
|
## 7. Verdict
|
|
|
|
- **✅ Accepté** : scripts/profils prêts à planifier.
|
|
- **🟡 Accepté avec réserves** : profils à compléter.
|
|
- **❌ Rejeté** : interactivité SSH, secrets, risques non validés ou JSON absent.
|
|
|
|
---
|
|
|
|
## 8. Notes de validation
|
|
|
|
**Date** : 2026-06-05 — Gilles Soulier (orchestrateur, validation déléguée)
|
|
|
|
---
|
|
|
|
### Verdict global : 🟡 Accepté avec réserves
|
|
|
|
Le design est solide dans ses fondements : non-interactivité, JSON canonique, profils minimum, cycle precheck/install/configure/initialize/verify/report, taxonomie d'erreurs, secrets exclus. Les réserves ci-dessous sont mineures et n'invalident pas la mise en planification, sous réserve qu'elles soient traitées avant ou pendant l'implémentation.
|
|
|
|
---
|
|
|
|
### Résultat case par case
|
|
|
|
#### Section 1 — Discipline & périmètre
|
|
|
|
- [x] Aucun script de production ajouté/modifié. Confirmé : la tâche est design seul.
|
|
- [x] Aucun `curl | sh` opaque validé sans justification. §6 exige URL officielle, checksum si disponible, confirmation. **Note** : `rustup`, `nvm`, `uv` sont pré-autorisés par leur liste en §14 — ce statut devrait être rendu explicite dans la spec (note « installateur pré-autorisé justifié »).
|
|
- [x] Aucun secret en clair. §6 + §12 clairs.
|
|
- [x] Templates versionnés sur disque. §6 + §13 checklist.
|
|
- [x] Tout script non interactif. §2 + §13.
|
|
|
|
#### Section 2 — Profils minimum
|
|
|
|
- [x] `bootstrap_root` — §3.
|
|
- [x] `identity_network` — §3 avec variables JSON.
|
|
- [x] `base_tools` sans `vim` — §3, explicitement listé.
|
|
- [x] `network_tools` avec `nmap` classé admin local contrôlé — §3, classé "outil réseau d'administration pour découverte locale", distinction security_audit/security_lab présente.
|
|
- [x] `dev_git` — §3.
|
|
- [x] `sharing` avec Samba/NFS/mDNS/wsdd2 — §3 + §5 exemples JSON complets.
|
|
- [x] `docker_official` — §3, modélisé comme installateur externe officiel.
|
|
- [x] `home_automation` — §4.
|
|
- [x] `dev_tools` — §4.
|
|
- [x] `embedded_esp_platformio` — §4, groupes dialout/plugdev, règles udev.
|
|
- [x] `terminal_customization` — §8, variables UI + JSON retour.
|
|
|
|
#### Section 3 — Hardware, OS et métriques
|
|
|
|
- [x] `machine_probe` spécifié — §3, JSON de sortie complet avec recommendations.
|
|
- [x] `machine_metrics_simple` spécifié — §3, JSON de sortie complet, non destructif.
|
|
- [x] `apt_repositories` spécifié — §3, analyse puis action séparée validée.
|
|
- [x] `firmware_tools` spécifié — §3, règles VM/bare-metal/Proxmox.
|
|
- [x] `gpu_drivers` spécifié — §3, sous-profils nvidia/amd/intel/intel_arc, séquence en trois étapes.
|
|
- [x] `benchmark_tools` spécifié — §3, confirmation explicite, rapport JSON, optionnel.
|
|
- [x] Scripts dépendent du couple OS/type machine — §3 machine_probe détecte virtualization/raspberryPi/proxmoxHost, §13 checklist.
|
|
- [x] Drivers/firmware/benchmark non installés par défaut — §3 ("optionnels et jamais installés par défaut"), §12 définition de terminé.
|
|
|
|
#### Section 4 — Manifestes et champs UI
|
|
|
|
- [x] Chaque profil possède id, label, description, risque, fields, defaults, validations. **Coquille corrigée** : le manifeste JSON exemple §2 ne comportait pas `description`, `defaults`, `validations` — ajoutés lors de la présente revue.
|
|
- [~] Cocher un profil déplie les champs obligatoires. Comportement UI non décrit dans tache4.md. Relève principalement de la tâche 3 (formulaires) ; la tâche 4 ne fixe que les champs déclarés dans le manifeste. Acceptable dans le périmètre tâche 4.
|
|
- [~] Bouton run désactivé si champs requis invalides. Non mentionné dans tache4.md. Relève de la tâche 3. Acceptable.
|
|
- [x] Preview template avec masquage secrets. §6 "prévisualisable" + principe "sans secret en clair". La formulation explicite "masquage secrets lors de la preview" est absente mais découlée du principe général. **Réserve légère** : à formuler explicitement lors de l'implémentation.
|
|
- [x] `human_interaction_required` plutôt que blocage SSH. §10 taxonomie d'erreurs, présent.
|
|
|
|
#### Section 5 — Cycle d'exécution
|
|
|
|
- [x] `precheck` — §2 + §7.
|
|
- [x] `install` — §2 + §7.
|
|
- [x] `configure` — §2 + §7.
|
|
- [x] `initialize` — §2 + §7.
|
|
- [x] `verify` — §2 + §7.
|
|
- [x] `report JSON` — §2 + §9.
|
|
- [x] Sauvegardes de fichiers système avant modification. §6 "rollback ou sauvegarde quand un fichier système est modifié" + §8 terminal_customization `backupFiles` dans JSON retour.
|
|
- [~] Reboot/reconnexion signalés et intégrés à `reboot_verified`. `requiresReboot`/`requiresRelogin` présents dans le JSON de retour. **Réserve** : la confirmation post-reboot (`reboot_verified`) — c'est-à-dire le booléen attestant que la machine a redémarré et est de nouveau joignable — n'est pas explicitement nommée. §3 identity_network mentionne "reboot vérifié si nécessaire" mais le champ JSON correspondant est absent du modèle canonique §9. À ajouter.
|
|
|
|
#### Section 6 — JSON et erreurs
|
|
|
|
- [x] JSON d'entrée défini — §3 variables UI identity_network, §5 Samba/NFS, §8 terminal.
|
|
- [x] JSON résultat défini — §2, §3, §5, §8, §9 champs communs.
|
|
- [x] Liste paquets/services/fichiers modifiés incluse — §5 packagesInstalled/filesChanged/services, §9.
|
|
- [x] Taxonomie erreurs présente — §10, 16 codes distincts.
|
|
- [x] Logs bruts archivés, lignes importantes réduites — §9 "Le log brut reste archivé. Hermes/MCP ne reçoivent que le JSON réduit et les lignes importantes."
|
|
|
|
---
|
|
|
|
### Réserves majeures (à traiter avant ou en début d'implémentation)
|
|
|
|
**R1 — Destination BDD des résultats machine_probe et machine_metrics_simple non spécifiée**
|
|
La tâche 4 ne mentionne pas explicitement que le JSON de sortie de `machine_probe` alimente `machine_hardware` et que `machine_metrics_simple` alimente `machine_metrics_latest` (tables définies dans tache1.9.md §9). Cette liaison doit être documentée dans les livrables sous `docs/` avant que la tâche 5 (exécution backend) ne commence à router ces résultats.
|
|
|
|
**R2 — Champ `reboot_verified` absent du JSON canonique §9**
|
|
Le JSON commun de §9 contient `requiresReboot` (intention) mais pas de champ attestant que le reboot a effectivement été vérifié. Le cycle identity_network exige "reboot vérifié" — le contrat JSON doit porter ce champ (ex. `rebootVerified: boolean | null`).
|
|
|
|
**R3 — Installateurs `curl | sh` (rustup, nvm, uv) non explicitement justifiés dans la spec**
|
|
Ces installateurs sont listés dans §4 et §14 mais la spec ne les désigne pas formellement comme "pré-autorisés avec justification documentée" conformément à la règle §6. La liste des installateurs autorisés avec leurs URLs officielles et la stratégie de vérification (checksum interne rustup-init, hash nvm/install.sh via GitHub release) devrait apparaître dans un tableau dans les livrables `docs/`.
|
|
|
|
**R4 — Masquage des secrets lors de la preview template non formulé**
|
|
Le principe "sans secret en clair" est global mais la preview de template (§6 "prévisualisable") ne précise pas comment les variables sensibles (password, token) sont masquées dans l'affichage UI. À formaliser explicitement dans la spec des installateurs externes.
|
|
|
|
---
|
|
|
|
### Réserves mineures (à noter, non bloquantes)
|
|
|
|
- Le manifeste JSON exemple §2 ne contenait pas `description`, `defaults`, `validations` — **corrigé lors de la présente revue**.
|
|
- Le backup path §8 terminal_customization comportait une date figée en dur — **corrigé lors de la présente revue** (remplacé par `{{backupDate}}`).
|
|
- `iotop` dans `base_tools` : sur certaines distributions récentes ce paquet requiert le kernel avec CONFIG_TASK_IO_ACCOUNTING ou peut s'appeler différemment. Non bloquant au niveau design mais à anticiper lors de l'implémentation avec un fallback.
|
|
- La distinction des trois niveaux nmap (network_tools / security_audit / security_lab) est bien documentée dans §3 et §4. Elle devrait être reprise dans le manifeste de chaque profil concerné (champ `risk` + note UI d'avertissement pour security_lab).
|
|
|
|
---
|
|
|
|
### Coquilles corrigées dans tache4.md
|
|
|
|
1. **§2 manifeste JSON** : ajout de `"description"`, `"defaults": {}`, `"validations": []` pour correspondre au gate §4 qui exige ces trois champs dans chaque manifeste de profil.
|
|
2. **§8 terminal_customization, JSON retour `backupFiles`** : date figée `20260605` remplacée par le placeholder Mustache `{{backupDate}}` pour indiquer que la valeur est dynamique à l'exécution.
|
|
|
|
---
|
|
|
|
### Cohérence inter-tâches
|
|
|
|
- **Tâche 2 (moteur templates)** : tache4.md s'appuie correctement sur Mustache + templates versionnés sur disque, conforme à tache2.md. Aucun moteur parallèle créé. OK.
|
|
- **Tâche 1.9 (BDD)** : tables `install_profiles`, `install_recipes`, `install_recipe_versions`, `machine_profile_state`, `script_variables_presets`, `machine_hardware`, `machine_metrics_latest` sont bien définies dans tache1.9.md §9. La liaison explicite depuis tache4.md vers ces tables est manquante (réserve R1 ci-dessus).
|
|
- **Tâche 3 (formulaires UI)** : les comportements "déplier champs" et "désactiver bouton run" relèvent de tache3.md et ne sont pas à spécifier dans tache4.md. Frontière correcte.
|
|
- **Tâche 5 (exécution)** : les JSON d'entrée/sortie définis dans tache4.md constituent les contrats que tache5 devra respecter pour le routage et le stockage. Dépendance correctement identifiée en §15.
|
|
- **client.ts / templates APT existants** : le modèle d'exécution (sudo -S, base64, marqueurs ===SU:XXX===, non interactif) est cohérent avec les conventions. Les scripts post-install de tache4 doivent émettre les marqueurs de section appropriés ou un JSON terminal en remplacement — la spec tache4 choisit le JSON terminal, ce qui est cohérent avec l'intention d'évolution décrite dans tache2 (JSON-in-shell).
|
|
|
|
---
|
|
|
|
### Conclusion
|
|
|
|
Le design tache4.md est **prêt à entrer en planification d'implémentation** sous réserve du traitement des quatre réserves majeures ci-dessus, en priorité R1 (liaison BDD) et R2 (champ reboot_verified), qui sont nécessaires pour que la tâche 5 puisse router correctement les résultats.
|