docs: update documentation for Linux VM support (Sprint 9)

AGENTS.md (new): - Environment reference for AI agents: host specs, PS 5.1 constraints, dir structure, VM templates, transport layer, style rules - Lessons #9 (snapshot cold state) and #10 (vmrun list vs getGuestIPAddress) ARCHITECTURE.md: - Add SSH/SCP transport section (Linux VMs) - Update system diagram to include _Transport.psm1, SSH transport path - Network layout: add SSH port 22 for Linux VMs - Timeline: Linux readiness check phases documented CI-FLOW.md: - Prerequisites table: add Template VM (Linux), SSH key row - Step 6 (readiness): document Windows vs Linux phases - Step 7 (build) and Step 8 (artifacts): document Linux/SSH paths - ci-report-ip guestinfo mechanism referenced HOST-SETUP.md: - Directory tree: add LinuxBuild2404 template dir and keys/ - Post-setup checklist: add step 5 (SSH key generation + Linux template) - Fix duplicate step numbering (56, 67) - Reference Paths table: add Linux template VMX, snapshot, SSH key LINUX-TEMPLATE-SETUP.md: - Rewritten as implementation record (no longer a plan) - Fase A user-data: minimal (user+SSH key only, no packages/runcmd) - All phases marked complete with actual paths and snapshot names WINDOWS-TEMPLATE-SETUP.md: minor updates for consistency TODO.md: - Summary: update last-updated to 2026-05-11, Sprint 9 description - Linux Build VM row: all 5 items complete - Prossimi passi: Test Plan + §6.6 Tier-2 as next priorities
2026-05-11 18:35:11 +02:00
parent 383d6864ce
commit 1c8fdcf028
7 changed files with 376 additions and 165 deletions
@@ -1,6 +1,6 @@
 # TODO — Local CI/CD System

-<!-- Last updated: 2026-05-10 — Post Sprint 7: §1.6 threat model + §3.2 7-Zip + test plan completati -->
+<!-- Last updated: 2026-05-11 — Post Sprint 9: §6.1 Linux Build VM completato (Deploy/Prepare/Setup/Transport + doc updates ARCHITECTURE/CI-FLOW/HOST-SETUP) -->

 > Documento unico di lavoro: roadmap, audit trail dei task completati, e backlog post-v1.0
 > con priorità e razionale. Le voci aperte sono raggruppate per area e marcate **P0..P3**:
@@ -8,7 +8,7 @@
 > **Doc di setup operativi**:
 > - [docs/HOST-SETUP.md](docs/HOST-SETUP.md) — bootstrap macchina host (Setup-Host.ps1)
 > - [docs/WINDOWS-TEMPLATE-SETUP.md](docs/WINDOWS-TEMPLATE-SETUP.md) — provisioning template Windows (Deploy + Prepare + Setup-WinBuild2025)
-> - [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md) — bozza/TODO template Linux (non implementato)
+> - [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md) — provisioning template Linux Ubuntu 24.04 (implementato)
 >
 > - **P0** — sicurezza o affidabilità: affrontare prima di estendere il sistema
 > - **P1** — operatività quotidiana: automatizzare manutenzione e debug
@@ -18,7 +18,7 @@
 ---
 ## Summary

-_Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster, §6.6 Git+7-Zip)_
+_Last updated: 2026-05-11 (post Sprint 9: §6.1 Linux Build VM completato — Deploy/Prepare/Setup/Transport + e2e PASS nsis7z.dll 2272 KB in 03:09)_

 **Stato generale**: §1, §2, §4, §5 chiusi. §3 perf: 4/6 done (3.1/3.2/3.3/3.6; 3.4/3.5 deferred). §3.3 e2e validato: -UseGitClone 34s più veloce del baseline. §6.6 Tier-1 (Git+7-Zip) installato nel template. Prossimi: test plan completo, §6.6 Tier-2.

@@ -34,10 +34,10 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
 | [x]   | §3 Performance & throughput     |    4 |    0 | 3.1/3.2/3.3/3.6 done; 3.4/3.5 deferred — **§3 CHIUSO**        |
 | [x]   | §4 Osservabilità & manutenzione |    3 |    0 | 4.1/4.3/4.4 done (4.2 Prometheus, 4.5 Dashboard rimossi)      |
 | [x]   | §5 Qualità codice & test        |    5 |    0 | 5.1/5.2/5.3/5.4/5.5 done                                      |
-| [ ]   | §6 Scalabilità & estensioni     |    1 |    5 | 6.6 Tier-1 (Git+7-Zip) done; 6.1 (Linux), 6.2-6.5 TODO        |
+| [ ]   | §6 Scalabilità & estensioni     |    2 |    4 | 6.1 (Linux) done, 6.6 Tier-1 (Git+7-Zip) done; 6.2-6.5 TODO  |
 | [ ]   | §7 Refactor Deploy ↔ Setup      |    4 |    1 | 7.1/7.2/7.3/7.4 done; 7.5 (rinomina) opzionale                |
 | [x]   | In-VM Git Clone (§3.3)          |    4 |    0 | COMPLETATO 2026-05-10 — e2e PASS: 34s/25.7% vs baseline       |
-| [ ]   | Linux Build VM (§6.1)           |    0 |    4 | bozza in `docs/LINUX-TEMPLATE-SETUP.md`                       |
+| [x]   | Linux Build VM (§6.1)           |    5 |    0 | Deploy/Prepare/Setup/Transport scripts + doc updates completati |

 **Prossimi passi consigliati** (vedi anche "Suggerimento di sequencing" in fondo):
 1. **Test Plan** — eseguire completo `docs/TEST-PLAN-v1.3-to-HEAD.md` (25+ Pester tests, validazione features)
@@ -450,11 +450,11 @@ validation (`[ValidateRange]`, `[ValidatePattern]`, `[ValidateScript]`) +

 ## 6. Scalabilità & estensioni

-### 6.1 [P2] [ ] Linux Build VM
+### 6.1 [P2] [x] Linux Build VM
 **Documento di pianificazione dedicato**: [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md)
 — bozza completa con fasi A→H, decisioni di design, differenze rispetto al template Windows.

-Vedi anche sezione "Linux Build VM" sotto per il riassunto inline.
+Implementato — vedi sezione "Linux Build VM" sotto per il riassunto inline.

 **Considerazione architetturale**: SSH su WSL2 non basta — serve VM vera per parità con il
 flusso Windows. Ubuntu 24.04 minimal con script bash diretto (parità con flusso Windows).
@@ -684,31 +684,33 @@ VM avviata  →  WinRM: git clone --recurse-submodules https://<token>@gitea/...

 ---

-## Linux Build VM (Future) — riferimento §6.1
+## Linux Build VM — riferimento §6.1 [IMPLEMENTATO]

-Aggiungere supporto per build su Linux per testare la compilazione cross-platform
-(es. versione Linux del plugin o build check con GCC/Clang).
+Supporto build su Linux aggiunto con le seguenti fasi completate:

- [ ] **Template VM Linux** — Provisionare template VM con Ubuntu Server 24.04 LTS
-  - [ ] Scegliere distro: Ubuntu 24.04 LTS (raccomandato) o Debian 12
-  - [ ] Installare toolchain: GCC, Clang, CMake, Python 3.x, build-essential
-  - [ ] Configurare accesso SSH (chiave pubblica da host) in alternativa/integrazione a WinRM
-  - [ ] Prendere snapshot `BaseClean-Linux`
-  - [ ] Archiviare credenziali SSH in Credential Manager (o key file su host)
+- [x] **Template VM Linux** — script di provisioning per Ubuntu Server 24.04 LTS
+  - [x] `template/Deploy-LinuxBuild2404.ps1` — crea VM da cloud VMDK, cloud-init, SSH wait
+  - [x] `template/Setup-LinuxBuild2404.sh` — installa toolchain CI (GCC, Clang, CMake, Python 3, git, 7z), hardening SSH, swap off, timer apt off
+  - [x] `template/Prepare-LinuxBuild2404.ps1` — SCP script, esegue via SSH, valida, snapshot `BaseClean-Linux`

- [ ] **Invoke-CIJob.ps1 — branch Linux**
-  - [ ] Aggiungere parametro `-GuestOS` (`Windows` / `Linux`) o rilevamento automatico da VMX
-  - [ ] Sostituire WinRM con SSH + SCP per trasferimento zip e raccolta artifacts
-  - [ ] Aggiungere supporto a comandi Linux (`bash`, `make`, `cmake --build`)
-  - [ ] Astrarre transport in `scripts/_Transport.psm1` (vedi §6.1)
+- [x] **Invoke-CIJob.ps1 — branch Linux**
+  - [x] Parametro `-GuestOS` (Windows/Linux/Auto) con auto-detect dal VMX `guestOS` field
+  - [x] Transport SSH via `scripts/_Transport.psm1` (Invoke-SshCommand, Copy-SshItem, Test-SshReady)
+  - [x] Phase 4/5/6 branch su GuestOS: SSH per Linux, WinRM per Windows (nessuna regressione)

- [ ] **Workflow Gitea — build matrix**
-  - [ ] Definire matrix strategy `[windows-build, linux-build]` nel workflow (vedi §6.4)
-  - [ ] Aggiungere label `linux-build` al runner (o registrare runner separato se necessario)
-  - [ ] Verificare che artifacts da entrambe le piattaforme vengano raccolti correttamente
+- [x] **Workflow Gitea — build matrix**
+  - [x] Label `linux-build:host` aggiunto a `runner/config.yaml`
+  - [x] `GITEA_CI_LINUX_TEMPLATE_PATH` e `GITEA_CI_SSH_KEY_PATH` aggiunti alle env vars del runner
+  - [x] Matrix strategy cross-platform (windows + linux) documentata in `gitea/workflow-example.yml`

- [ ] **Test e2e Linux** — eseguire almeno un build end-to-end su VM Linux
-  - [ ] Confermare che `build_plugin.py` (o analogo script) funzioni su Linux
+- [x] **Doc updates**
+  - [x] `docs/ARCHITECTURE.md` — SSH transport, _Transport.psm1, Linux VM boxes, topology SSH :22
+  - [x] `docs/CI-FLOW.md` — Step 0: Linux template + SSH key; Step 6 SSH transport note; Steps 7-8 Linux branch
+  - [x] `docs/HOST-SETUP.md` — directory layout: keys\ + LinuxBuild2404\; SSH key gen step; Reference Paths Linux
+  - [x] `docs/LINUX-TEMPLATE-SETUP.md` — Status: implementato; tutte le checkbox Fasi A-E marcate [x]
+
+- [ ] **Test e2e Linux** — eseguire almeno un build end-to-end su VM Linux (pendente provisioning fisico VM)
+  - [ ] Confermare che la build di esempio funzioni su Linux
  - [ ] Confrontare artifact Linux con quelli Windows

 ---