From 0f99549b70a31029cf09402663f646ff03ac5409 Mon Sep 17 00:00:00 2001 From: Simone Date: Sun, 17 May 2026 23:29:19 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20implementation-plan-A-B=20=E2=80=94=20P?= =?UTF-8?q?hase=20A=20closed,=20B=20kept=20as=20forward=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Medium update: exec-summary status (A COMPLETATA, B ready), master checklist A items [x], Phase A gating satisfied, §1 COMPLETATA banner with real validation deviations (LocalSystem venv/keyring, github-free artifacts, transport, shim common-params, deferred §8.1/§8.2), §7 A-side definition-of-done [x]. Fase B (§2/§3/§4) + risk matrix + cronoprogramma left intact as the Phase B design reference alongside PhaseB-user-checklist.md. Co-Authored-By: Claude Opus 4.7 --- plans/implementation-plan-A-B.md | 73 +++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 19 deletions(-) diff --git a/plans/implementation-plan-A-B.md b/plans/implementation-plan-A-B.md index 7d785fe..97148f1 100644 --- a/plans/implementation-plan-A-B.md +++ b/plans/implementation-plan-A-B.md @@ -14,11 +14,15 @@ Sintesi fasi: - Output verificabile: `python -m ci_orchestrator job ...` sostituisce `Invoke-CIJob.ps1`; `pytest` ≥70% coverage; workflow `build-ns7zip.yml` PASS. - - Stato: da iniziare. + - **Stato: COMPLETATA** ✅ — validata end-to-end (vedi + `plans/PhaseA-user-checklist.md` Passi 1-9), merge `feature → + main` `2aa12bb`, tag `v2.0.0-phaseA`. Dettaglio storico in §1. - **Fase B — Migrazione host a Linux Mint + Workstation Pro Linux** - Output verificabile: act_runner come `act-runner.service` systemd; storage `/var/lib/ci/`; burn-in 4 job concorrenti PASS. - - Stato: da iniziare (gating: A done). + - **Stato: pronta** (gating "A done" soddisfatto). Esecuzione via + `plans/PhaseB-user-checklist.md`; design/rischi/cronoprogramma in + §2/§3/§5/§6 di questo piano. - **Fase C — (Hook only, non implementata) backend ESXi via `pyVmomi`** - Output verificabile: Protocol `VmBackend` rispettato; `[backend]` selector in `config.toml`. @@ -50,7 +54,7 @@ A4; cambiano solo path/env vars in Fase B). - [x] [A1] Implementare `transport/winrm.py` con wrapper `pypsrp.client.Client` - [x] [A1] Implementare `transport/ssh.py` con wrapper `paramiko.SSHClient` / `SFTPClient` - [x] [A1] Implementare `credentials.py` con Protocol `CredentialStore` + `KeyringCredentialStore` -- [ ] [A1] PoC `wait-ready` end-to-end via `pypsrp` contro un guest Windows reale +- [x] [A1] PoC `wait-ready` end-to-end via `pypsrp` contro un guest Windows reale (smoke self-test PASS) - [x] [A1] Test pytest unitari per `vmrun.py`, `winrm.py`, `ssh.py`, `credentials.py` con mock - [x] [A1] Aggiungere job pytest a `gitea/workflows/lint.yml` - [x] [A2] Portare `Wait-VMReady.ps1` → `python -m ci_orchestrator wait-ready` @@ -67,12 +71,12 @@ A4; cambiano solo path/env vars in Fase B). - [x] [A4] Portare `Invoke-CIJob.ps1` → `python -m ci_orchestrator job` - [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-ns7zip.yml` (matrix Win+Linux) end-to-end PASS +- [x] [A4] Eseguire workflow `build-ns7zip.yml` (matrix Win+Linux) end-to-end PASS (+ job release validato con tag throwaway) - [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 +- [x] [A5] Eseguire burn-in 4 job concorrenti PASS (Start-BurnInTest: 3 round × 4 = 12/12, 0 orfani) - [ ] [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 - [ ] [B1] Configurare `vmnet8` NAT range `192.168.79.0/24` (allineato all'host Windows) @@ -106,16 +110,47 @@ A4; cambiano solo path/env vars in Fase B). Da soddisfare prima di iniziare A1: -- [ ] Repo `local-ci-cd-system` clonato e workflow `lint.yml` + `self-test.yml` verdi sull'host Windows attuale -- [ ] Backup integro di `F:\CI\Templates\` (snapshot `BaseClean` validato con `vmrun listSnapshots`) -- [ ] Python 3.11+ installato sull'host Windows e disponibile come `python` nel PATH dell'utente che gira act_runner -- [ ] Accesso amministrativo a Gitea per registrare/de-registrare runner durante A4 e B4 -- [ ] Credenziali `BuildVMGuest` e `GiteaPAT` esistenti nel Credential Manager Windows e leggibili dall'utente di servizio -- [ ] `AGENTS.md` letto integralmente da chi esegue il piano (errori #1–#12 sono test case obbligatori) +> Prerequisiti Fase A **soddisfatti** (Fase A completata). Per `BuildVMGuest` +> emerso in validazione: deve stare nel vault **LocalSystem** (act_runner +> service), username host-qualificato — vedi `scripts/Set-CIGuestCredential.ps1`. + +- [x] Repo `local-ci-cd-system` clonato e workflow `lint.yml` + `self-test.yml` verdi sull'host Windows attuale +- [x] Backup integro di `F:\CI\Templates\` (snapshot `BaseClean` validato con `vmrun listSnapshots`) +- [x] Python 3.11+ installato sull'host Windows (venv produzione `F:\CI\python\venv`, install **non-editable**) +- [x] Accesso amministrativo a Gitea per registrare/de-registrare runner durante A4 e B4 +- [x] Credenziali `BuildVMGuest` e `GiteaPAT` nel vault SYSTEM (LocalSystem), username host-qualificato +- [x] `AGENTS.md` letto integralmente da chi esegue il piano (errori #1–#12 sono test case obbligatori) - [ ] Hardware target Linux Mint disponibile fisicamente (può restare spento fino a B1) ## 1. Fase A — Rewrite Python (host Windows attuale) +> **✅ FASE A COMPLETATA E VALIDATA END-TO-END.** +> Merge `feature/python-rewrite-and-linux-migration → main` (`2aa12bb`), +> tag `v2.0.0-phaseA`. Validazione: `plans/PhaseA-user-checklist.md` +> Passi 1-9 (smoke wait-ready/job Win+Linux, self-test entrambi i +> transport, `build-ns7zip.yml` matrix + job release, burn-in 12/12, +> benchmark). Le sottosezioni A1-A5 sotto sono **record storico** del +> piano; lo stato reale è negli `[x]` della checklist master e nel +> checklist utente. +> +> **Deviazioni/scoperte rilevanti in validazione** (non previste dal +> piano originale, ora gestite): +> - venv produzione = install **non-editable** (act_runner=LocalSystem; +> `-e` punta a path non risolti → `No module named ci_orchestrator`). +> `lint.yml` non deve installare nella venv condivisa (venv effimera). +> - Credenziali (`BuildVMGuest`, `GiteaPAT`) nel vault **SYSTEM** non +> utente; username WinRM **host-qualificato**; transport WinRM forza +> `auth=ntlm`. Helper: `scripts/Set-CIGuestCredential.ps1`, +> `scripts/Test-CIGuestWinRM.ps1`. +> - Gitea: `DEFAULT_ACTIONS_URL=github` + `uses:` URL completo; repo +> action **pubblico**; `upload/download-artifact@v4`→`@v3` (GHES); +> artifact **github-free** (handoff via filesystem host). +> - Transport sorgente: `use-git-clone`/`submodules` default ON; +> variante host-side clone (`--host-clone`) per SSH alias host-only. +> - Shim PS: i forwarder ciechi NON inoltrano i common param PS. +> - Deferred (non bloccanti, `TODO.md`): §8.1 mirror `actions/checkout` +> su Gitea, §8.2 streaming live output build Windows. + ### A1 — Bootstrap progetto + moduli core **Obiettivo**: creare scheletro package Python con `VmBackend`, transport @@ -344,8 +379,8 @@ qualche caller esterno non ancora migrato emerge. - [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) +- [x] Burn-in PASS — `Start-BurnInTest.ps1` 3 round × 4 job = 12/12, 0 orfani +- [x] **Fase A done**: validata end-to-end su hardware reale; mergiata in `main` (`2aa12bb`), tag `v2.0.0-phaseA` ## 2. Fase B — Migrazione host Linux Mint @@ -980,11 +1015,11 @@ Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item. ## 7. Definizione di "fatto" globale (A+B) -- [ ] Tutti gli script `scripts/*.ps1` portati a Python o ridotti a shim (eccetto `template/*.ps1` e `Install-CIToolchain-*.ps1` che restano PS by design) -- [ ] `Invoke-CIJob.ps1` non più referenziato nei workflow YAML -- [ ] `pytest` verde con coverage ≥70% su `src/ci_orchestrator/` -- [ ] `ruff check` + `mypy --strict` puliti su tutto `src/` -- [ ] `lint.yml` dual-stack (PSSA per PS legacy + ruff/mypy/pytest per Python) PASS +- [x] Tutti gli script `scripts/*.ps1` portati a Python o ridotti a shim (eccetto `template/*.ps1` e `Install-CIToolchain-*.ps1` che restano PS by design) +- [x] `Invoke-CIJob.ps1` non più referenziato nei workflow YAML (action invoca la CLI Python) +- [x] `pytest` verde con coverage ≥70% su `src/ci_orchestrator/` +- [x] `ruff check` + `mypy --strict` puliti su tutto `src/` +- [x] `lint.yml` dual-stack (PSSA per PS legacy + ruff/mypy/pytest per Python) PASS - [ ] act_runner gira come `act-runner.service` systemd su Linux Mint - [ ] Tutti i template VM (`WinBuild2025`, `WinBuild2022`, `LinuxBuild2404`) operativi dal nuovo host con snapshot integri - [ ] Workflow `build-ns7zip.yml` matrix Win+Linux PASS dal nuovo host @@ -995,7 +1030,7 @@ Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item. - [ ] `README.md`, `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/HOST-SETUP.md`, `docs/CI-FLOW.md`, `docs/RUNBOOK.md` aggiornati allo stato finale - [ ] ≥1 settimana di esercizio in produzione su host Linux senza incidenti - [ ] Backup `F:\CI\` archiviato e validato -- [ ] Hook §4 (Protocol `VmBackend`, factory backend, naming neutro) presenti nel codice e referenziati in `docs/ARCHITECTURE.md` +- [x] Hook §4 (Protocol `VmBackend`, factory backend, naming neutro) presenti nel codice e referenziati in `docs/ARCHITECTURE.md` ## 7.1 Auto-check