From a658f4ed3bb03482f9929989e0606af3932dce71 Mon Sep 17 00:00:00 2001 From: Simone Date: Thu, 14 May 2026 17:39:47 +0200 Subject: [PATCH] docs(a5): mark A5 as code-complete; add A5-closeout.md Master checklist + step A5 attivita + 'definizione di fatto' updated; A5-closeout.md added (116 pytest, coverage 80.10% total, gate raised to 80%). Hardware validation (burn-in 4x10 + workflow matrix end-to-end) deferred to user. Shim PS removal deferred to B5 (systemd timers): all 10 shims still referenced by Register-CIScheduledTasks.ps1 / docs / Test-*.ps1. --- plans/A5-closeout.md | 100 +++++++++++++++++++++++++++++++ plans/implementation-plan-A-B.md | 36 +++++------ 2 files changed, 118 insertions(+), 18 deletions(-) create mode 100644 plans/A5-closeout.md diff --git a/plans/A5-closeout.md b/plans/A5-closeout.md new file mode 100644 index 0000000..9a317cf --- /dev/null +++ b/plans/A5-closeout.md @@ -0,0 +1,100 @@ +# A5 — Closeout + +Fase A5 di `plans/implementation-plan-A-B.md`: polish, regression test +per gli errori frequenti `AGENTS.md` #9-#12, documentazione Python +allineata, gate coverage alzato a 80%. +Branch: `feature/python-rewrite-phase-a`. + +## Stato attuale + +- [x] `tests/python/test_agents_errors.py` aggiunto: 12 test dedicati che + coprono regressioni per `AGENTS.md` "Errori frequenti da evitare" + #9, #10, #11, #12. + - **#9** (snapshot template con VM accesa): `clone_linked` propaga + "should not be powered on" come `BackendOperationFailed` (subclass + di `BackendError`) con `operation == "clone"` e `output` che + contiene il messaggio originale di `vmrun`. + - **#10** (`vmrun getGuestIPAddress` lento): `is_running` usa solo + `vmrun list`. Tre asserzioni — happy path, VM non listata, errore + di `vmrun list` — verificano che `getGuestIPAddress` non venga MAI + chiamato come fallback. + - **#11** (machine-id duplicato → DHCP collision): la safety net + orchestrator-side è che `vm new` non riusi mai un clone-name + (timestamp suffix); il test invoca `vm new` due volte con lo stesso + `--job-id` e verifica che `clone_linked` riceva due + `name`/`destination` distinti. Il fix template-side + (`truncate -s 0 /etc/machine-id`) resta documentato in + `template/Prepare-LinuxBuild2404.ps1`. + - **#12** (`& nativecmd 2>$null` non sopprime stderr in PS 5.1): + `SshTransport` usa `paramiko.AutoAddPolicy` di default con + `known_hosts=None`, non chiama mai `subprocess.run`/`Popen` + (incluso `ssh-keygen`/`ssh.exe`/`scp.exe`), e wrappa errori + paramiko (import mancante, `exec_command` exception, SFTP + `put`/`get`) come `TransportConnectError` invece di propagare + eccezioni nude. +- [x] `AGENTS.md` aggiornato: nuova sezione "Python development" subito + dopo "PowerShell 5.1 — Vincoli critici", con tabella parametri, + convenzioni (type hints, no `Any`/globali/`print`/`shell=True`), + mappatura completa PS → Python sub-command, elenco PS che restano + e gate coverage 80%. +- [x] `docs/ARCHITECTURE.md` esteso con sezione "Python orchestrator + (Phase A)": layout package, `VmBackend` Protocol, factory + `load_backend(config)`, ricetta Phase C per backend ESXi + (`backends/esxi.py` + selettore `[backend]` in `config.toml`), + transport selection, gate CI. +- [x] `README.md` ampliato: setup venv produzione + dev, esempi CLI per + tutti i 10 sub-comandi (`wait-ready`, `vm new/remove/cleanup`, + `build run`, `artifacts collect`, `monitor disk/runner`, + `report job`, `job`), comandi validazione locale con gate 80%, + link a `test_agents_errors.py` e `pyproject.toml`. +- [x] Suite completa: ruff clean, mypy --strict clean, **116 pytest + PASS**, coverage totale **80.10%** (gate 80% raggiunto). +- [ ] Burn-in 4 job concorrenti × 10 round (versione Python di + `Test-CapacityBurnIn`) — **richiede VM reali, lasciato a carico + utente**. +- [ ] Workflow `build-nsInnoUnp.yml` matrix (Win + Linux) end-to-end + PASS — eredita pendenza da A4 (richiede runner registrato). + +## Definizione di "fatto" A5 + +| Criterio | Stato | +| ----------------------------------------------------- | -------------------------------- | +| Errori #9–#12 coperti da test pytest | ✅ | +| `AGENTS.md` ha sezione "Python development" | ✅ | +| `docs/ARCHITECTURE.md` aggiornato (layout + hook C) | ✅ | +| `README.md` aggiornato (setup + esempi CLI) | ✅ | +| Coverage globale ≥80% (gate alzato in pyproject) | ✅ 80.10% | +| Shim PS non referenziati rimossi | ⏭️ nessuno candidato (vedi nota) | +| Burn-in 4×10 PASS | ⏳ utente — richiede VM reali | + +**Nota shim PS**: tutti i 10 shim (`Wait-VMReady.ps1`, `New-BuildVM.ps1`, +`Remove-BuildVM.ps1`, `Cleanup-OrphanedBuildVMs.ps1`, +`Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Watch-DiskSpace.ps1`, +`Watch-RunnerHealth.ps1`, `Get-CIJobSummary.ps1`, `Invoke-CIJob.ps1`) +sono ancora referenziati: `Register-CIScheduledTasks.ps1` registra +scheduled task che invocano `Watch-DiskSpace.ps1`, +`Watch-RunnerHealth.ps1`, `Cleanup-OrphanedBuildVMs.ps1`; `README.md` +documenta `Invoke-CIJob.ps1` per uso manuale; `Test-*.ps1` di smoke +chiamano gli shim. Nessuno shim è candidato a rimozione in A5 senza +prima migrare anche `Register-CIScheduledTasks.ps1` (Fase B5 lo +sostituirà con `*.service` + `*.timer` su systemd). + +## Cosa resta a carico utente + +1. Eseguire un burn-in concorrente (4 job × 10 round) usando il workflow + `build-nsInnoUnp.yml` matrix o `scripts/Test-CapacityBurnIn.ps1` (che + ora delega via shim alla CLI Python `job`) e verificare: + - PASS senza VM orfane (`vm cleanup` non rimuove nulla a fine round). + - Wall-clock entro ±20% del baseline pre-Python (`Measure-CIBenchmark.ps1`). +2. Validare `build-nsInnoUnp.yml` matrix (Win + Linux) end-to-end PASS + sul runner reale — pendenza ereditata da A4. +3. Validare `self-test.yml` e `lint.yml` post-switch. + +## Riferimenti commit + +- `test(a5): add pytest regression tests for AGENTS.md errors #9-#12` — + `tests/python/test_agents_errors.py` +- `docs(a5): document Python orchestrator in AGENTS.md, ARCHITECTURE.md, README.md` — + `AGENTS.md`, `docs/ARCHITECTURE.md`, `README.md` +- `docs(a5): mark A5 as code-complete; add A5-closeout.md` — + `plans/implementation-plan-A-B.md`, `plans/A5-closeout.md` diff --git a/plans/implementation-plan-A-B.md b/plans/implementation-plan-A-B.md index db6ab57..ca052e1 100644 --- a/plans/implementation-plan-A-B.md +++ b/plans/implementation-plan-A-B.md @@ -68,10 +68,10 @@ A4; cambiano solo path/env vars in Fase B). - [x] [A4] Aggiornare `gitea/actions/local-ci-build/action.yml` per invocare la CLI Python direttamente - [x] [A4] Forzare `PYTHONIOENCODING=utf-8` in `runner/config.yaml` - [ ] [A4] Eseguire workflow `build-nsInnoUnp.yml` (matrix Win+Linux) end-to-end PASS -- [ ] [A5] Convertire errori frequenti `AGENTS.md` #9, #10, #11, #12 in test pytest dedicati -- [ ] [A5] Aggiornare `AGENTS.md` con sezione "Python development" (venv, ruff, mypy, pytest) -- [ ] [A5] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout package -- [ ] [A5] Aggiornare `README.md` con setup Python +- [x] [A5] Convertire errori frequenti `AGENTS.md` #9, #10, #11, #12 in test pytest dedicati +- [x] [A5] Aggiornare `AGENTS.md` con sezione "Python development" (venv, ruff, mypy, pytest) +- [x] [A5] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout package +- [x] [A5] Aggiornare `README.md` con setup Python - [ ] [A5] Eseguire `Test-CapacityBurnIn` (versione Python) 4 job concorrenti PASS - [ ] [B1] Installare Linux Mint LTS + aggiornamenti su hardware target - [ ] [B1] Installare VMware Workstation Pro Linux (bundle ufficiale Broadcom) e validare `vmrun` su VM di test @@ -314,15 +314,15 @@ aggiornare documentazione, eseguire burn-in finale. **Attività**: -- [ ] Implementare test pytest dedicati per ognuno degli errori frequenti `AGENTS.md` #9 (snapshot powered-off), #10 (`vmrun list` vs `getGuestIPAddress`), #11 (machine-id reset), #12 (stderr handling — N/A per Python ma documentare) -- [ ] Rimuovere shim PS che non hanno call site esterni (verificare con `grep_search` che nessun task / doc li referenzia) -- [ ] Lasciare `Install-CIToolchain-*.ps1`, `Prepare-*.ps1`, `Deploy-*.ps1` in PowerShell (girano dentro guest o per ricostruzione template — vedi §4 di [idea-1](idea-1-python-rewrite.md)) -- [ ] Aggiornare `AGENTS.md`: aggiungere sezione "Python development" (venv path, ruff, mypy strict, pytest, encoding utf-8) -- [ ] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout `src/ci_orchestrator/` -- [ ] Aggiornare `README.md` con setup Python e quick-start CLI -- [ ] Portare `Test-CapacityBurnIn.ps1` in `commands/burnin.py` (o lasciare in PS se ancora utile come driver esterno) -- [ ] Eseguire burn-in 4 job concorrenti × 10 round PASS sull'host Windows -- [ ] Aggiornare `docs/RUNBOOK.md` con sezione "Operare da Python CLI" +- [x] Implementare test pytest dedicati per ognuno degli errori frequenti `AGENTS.md` #9 (snapshot powered-off), #10 (`vmrun list` vs `getGuestIPAddress`), #11 (machine-id reset → unique clone-name guard), #12 (stderr handling → AutoAddPolicy + no shell-out) +- [x] Verificare con `grep_search` che gli shim PS abbiano ancora call site esterni (`Register-CIScheduledTasks.ps1`, doc, `Test-*.ps1`) → nessuno candidato a rimozione in A5; rimozione differita a B5 (systemd timers) +- [x] Lasciare `Install-CIToolchain-*.ps1`, `Prepare-*.ps1`, `Deploy-*.ps1` in PowerShell (girano dentro guest o per ricostruzione template — vedi §4 di [idea-1](idea-1-python-rewrite.md)) +- [x] Aggiornare `AGENTS.md`: aggiungere sezione "Python development" (venv path, ruff, mypy strict, pytest, encoding utf-8, mappatura PS → Python) +- [x] Aggiornare `docs/ARCHITECTURE.md` con nuovo layout `src/ci_orchestrator/` + Phase C extension point +- [x] Aggiornare `README.md` con setup Python e quick-start CLI per tutti i 10 sub-comandi +- [ ] Portare `Test-CapacityBurnIn.ps1` in `commands/burnin.py` (o lasciare in PS se ancora utile come driver esterno) — non implementato in A5; lo shim attuale già delega via `job` Python +- [ ] Eseguire burn-in 4 job concorrenti × 10 round PASS sull'host Windows — richiede VM reali, a carico utente +- [ ] Aggiornare `docs/RUNBOOK.md` con sezione "Operare da Python CLI" — deferito a chiusura Fase B (RUNBOOK riscritto end-to-end in B-finale) **Hook futuri Fase C**: documentare in `docs/ARCHITECTURE.md` il contratto `VmBackend` come "extension point" e il selettore `[backend]` @@ -341,11 +341,11 @@ qualche caller esterno non ancora migrato emerge. **Definizione di fatto step A5**: -- [ ] Errori #9–#12 coperti da test pytest -- [ ] Documentazione aggiornata -- [ ] Shim non referenziati rimossi -- [ ] Burn-in PASS -- [ ] **Fase A done**: tutti i criteri di "fatto" §7 soddisfatti per la parte A +- [x] Errori #9–#12 coperti da test pytest (`tests/python/test_agents_errors.py`, 12 test) +- [x] Documentazione aggiornata (`AGENTS.md`, `docs/ARCHITECTURE.md`, `README.md`) +- [x] Shim non referenziati rimossi → nessuno candidato (tutti referenziati da `Register-CIScheduledTasks.ps1`/doc/`Test-*.ps1`); rimozione differita a B5 con sostituzione systemd +- [ ] Burn-in PASS — pendenza utente (richiede VM reali, vedi `plans/A5-closeout.md`) +- [ ] **Fase A done**: code-complete; pending solo validazioni hardware (burn-in + workflow matrix end-to-end) ## 2. Fase B — Migrazione host Linux Mint