Skip to content

feat(doctor): un diagnostic qui guide jusqu'au bout, et un --fix qui montre son plan (0.9.5) - #384

Merged
stephrobert merged 4 commits into
mainfrom
feat/doctor-guide
Nov 16, 2026
Merged

stephrobert merged 4 commits into
mainfrom
feat/doctor-guide

Conversation

@stephrobert

Copy link
Copy Markdown
Owner

Summary

Two empty machines measured on 2026-11-16 (Ubuntu 24.04, AlmaLinux 10) needed doctor to be run again after every gesture to discover the next one; three remedies were only links (git, Terraform, Docker); provision still failed after a green doctor (catalogue SSH key, ~/.ssh/config Include, EFI firmware never checked). Mock-ups and seven decisions were validated by the maintainer the same day.

  • Numbered steps in dependency order, one command per line, grouped by remedy; « Good to know », what is ready, then the single command dsoxlab doctor --fix. -v shows every check and warnings on green lines.
  • No hidden check: pool, groups and EFI wait for libvirt (after), collections wait for Ansible; with no provider chosen, the diagnosis follows the recommended one without recording it.
  • New checks: kvm/libvirt groups (join vs. log in again), EFI firmware, catalogue SSH key, Include line.
  • One remedy table per distribution family (/etc/os-release): official HashiCorp and Docker repositories, systemctl enable --now libvirtd, no dnf install incus on RHEL. docs/learner.md is held word for word against it by a test.
  • --fix: full plan, [y/N] or --yes (nothing runs without a terminal and without --yes), sudo steps through one generated ansible-playbook --ask-become-pass -c local run (Ansible installed first if missing), paste block as fallback, each step re-checked, stop at the first failure, Docker/Incus only with --clients.
  • Memory too small for the whole catalogue → « Good to know », non-blocking; start <lab> still blocks for its own lab.
  • JSON: commands, after, warning added per check, nothing removed. Exit codes unchanged.

Re-evaluated on two fresh VMs (Ubuntu 24.04.5, AlmaLinux 10.2 SELinux enforcing): one doctor pass shows every step, one doctor --fix does them all, then provision --host alma-rhcsa-1.lab succeeds and ssh alma-rhcsa-1.lab works by name. The re-evaluation found four defects, fixed in the follow-up commits (Include command failing on a missing ~/.ssh/config; --fix judging its own usermod failed; --clients installing KVM outside a catalogue and no Ansible for the playbook; EFI listed as manual). Not measured on a VM: the sudo-password path (the VM account has passwordless sudo), Fedora/Debian 13/Ubuntu 26.04, Docker/Incus via --clients (tests only).

Type of change

  • Bug fix
  • New feature
  • Refactor
  • Documentation
  • Chore / tooling
  • Security / supply chain

Checklist

Always

  • uv run ruff check src/dsoxlab tests tests_e2e fuzz scripts passes
  • uv run mypy src/dsoxlab passes (strict)
  • uv run pytest passes (2468 tests)
  • uv run pytest tests_e2e passes (18)
  • The engine stays domain-agnostic
  • No hardcoded personal path or host
  • Manually tested against two lab repositories: kubernetes-dsoxlab-training (vm, ready machine) and terraform-dsoxlab-training (no infra:), plus linux-dsoxlab-training on the two fresh VMs

Also: 28 mutations of the new safeguards, each fails at least one test; complexity ratchet stable.

When behavior changes — otherwise N/A

  • Both CHANGELOG.md and CHANGELOG.fr.md updated (under 0.9.5)
  • Version: N/A, already 0.9.5 in pyproject.toml (unreleased; this PR joins it)

When a command or option is added, removed or changed — otherwise N/A

  • Keys added to both en.py and fr.py
  • help=_("…") and fullhelp_commands updated in EN and FR (--yes, --clients, -v, new --fix)
  • Checked with DSOXLAB_LANG=en (VMs) and fr (local)
  • No new logger.* message

When .github/workflows/ is touched — otherwise N/A

N/A: no workflow touched.

When the declarative contract (meta.yml / lab.yaml) changes — otherwise N/A

N/A: the contract does not change.

Related issues

Refs #381 (EFI firmware now checked by doctor).

🤖 Generated with Claude Code

stephrobert and others added 4 commits November 16, 2026 10:42
…montre son plan

Parcours mesurés le 2026-11-16 sur deux machines vides (Ubuntu 24.04,
AlmaLinux 10) : il fallait relancer doctor après chaque geste pour voir le
suivant, trois remèdes n'étaient que des liens, et provision échouait encore
après un doctor vert (clé SSH, firmware EFI, Include ssh jamais contrôlés).
Maquettes et sept décisions validées par Stéphane le même jour.

- Étapes numérotées dans l'ordre des dépendances, une commande par ligne,
  regroupées par remède ; « À savoir », déjà prêt, commande unique.
- Aucun contrôle caché : pool, groupes, EFI attendent libvirt ; collections
  attendent Ansible ; provider non choisi = diagnostic avec le recommandé.
- Nouveaux contrôles : groupes kvm/libvirt, firmware EFI, clé SSH du
  catalogue, ligne Include de ~/.ssh/config.
- Table unique des remèdes par famille (/etc/os-release) : git, Terraform,
  Docker depuis les dépôts officiels ; enable --now libvirtd ; pas d'incus
  sur RHEL. La doc learner est tenue contre cette table par un test.
- --fix : plan affiché, [y/N] ou --yes, étapes root par un playbook généré
  et un seul ansible-playbook --ask-become-pass, repli à coller sans
  terminal, revérification après chaque étape, arrêt au premier échec,
  Docker/Incus seulement avec --clients.
- RAM de tout le catalogue : « À savoir », non bloquante ; start reste
  bloquant pour son lab.
- JSON : champs commands, after, warning ajoutés, rien retiré.

Le test qui joue la commande Include telle qu'affichée a trouvé qu'elle
échouait sur un ~/.ssh/config absent (cat en échec, && coupé) : corrigé.
28 mutations, 28 font tomber un test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nexion compte

Réévaluation du 2026-11-16 sur une Ubuntu 24.04 neuve : juste après le
usermod du playbook, /dev/kvm reste fermé dans la session, et hw_virt
proposait encore usermod ; --fix jugeait donc sa propre étape en échec et
s arrêtait, alors que pool et Terraform étaient faits. hw_virt distingue
désormais « inscrit, reconnectez-vous » comme le contrôle des groupes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… Ansible avant le playbook

Réévaluation du 2026-11-16 sur une AlmaLinux 10 neuve, sans git ni
catalogue : KVM, facultatif hors catalogue, aurait été installé par
--clients ; et la seule étape (git, root) tombait dans le repli « à
coller », faute d Ansible au plan. Décisions 1 et 3 du même jour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s, et Ansible se tait

Réévaluation du 2026-11-16 sur AlmaLinux 10 : le firmware EFI, qui
n attend que libvirt, était rangé en « à faire vous-même » et jamais
redit ; il est désormais revérifié après le playbook. Le playbook pose
ansible_python_interpreter=auto_silent : l avertissement de découverte de
python3 était la seule ligne jaune de --fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@stephrobert
stephrobert merged commit 857b099 into main Nov 16, 2026
21 checks passed
@stephrobert
stephrobert deleted the feat/doctor-guide branch November 16, 2026 10:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant