feat: enhance documentation and scripts for in-VM Git cloning and template setup

- Updated README.md to reflect the new in-VM git clone feature with `-UseGitClone`. - Modified Setup-Host.ps1 to correct VMX path references. - Revised various documentation files (ARCHITECTURE.md, CI-FLOW.md, HOST-SETUP.md, WINDOWS-TEMPLATE-SETUP.md) to include updated paths and features. - Added Setup-GiteaSSH.md for SSH configuration instructions. - Archived outdated documentation and updated README.md for clarity on current resources.
2026-05-10 23:03:56 +02:00
parent a60f7a4b90
commit 90a4396443
12 changed files with 114 additions and 64 deletions
@@ -0,0 +1,44 @@
+# Local CI/CD System — Design & Status
+
+## Sistema implementato e operativo (2026-05-08)
+
+### Hardware
+- Windows 11 host — CPU i9-10900X, 64 GB RAM, NVMe SSD
+
+### Hypervisor
+- VMware Workstation Pro
+- Template VM: Windows Server 2025
+  - VMX: `F:\CI\Templates\WinBuild\CI-WinBuild.vmx`
+  - Snapshot: `BaseClean`
+  - Toolchain: VS Build Tools 2026 (MSBuild 18.5.4 / v145), .NET SDK 10.0.203, Python 3.13.3
+
+### CI System
+- Gitea self-hosted — `http://10.10.20.11:3100`
+- act_runner v1.0.2 — Windows service su host, label `windows-build`
+- Build VMs: subnet VMnet8 NAT — `192.168.79.0/24`
+- WinRM HTTPS/5986 (Basic auth over HTTPS, self-signed cert, SkipCACheck lab-only)
+
+### Architettura implementata
+1. Gitea Actions enqueue job → act_runner lo prende
+2. `Invoke-CIJob.ps1` orchestra 6 fasi:
+   - **Phase 1**: `git clone` repo (con submoduli) su host in `C:\Temp\ci-src-<jobid>`
+   - **Phase 2**: `New-BuildVM.ps1` — linked clone da template snapshot `BaseClean`
+   - **Phase 3**: `vmrun start` VM headless
+   - **Phase 4**: `Wait-VMReady.ps1` — polling WinRM readiness (~5s)
+   - **Phase 5**: `Invoke-RemoteBuild.ps1` — trasferisce sorgente (zip), esegue build via WinRM, raccoglie `artifacts.zip`
+   - **Phase 6**: `Get-BuildArtifacts.ps1` — copia zip in `F:\CI\Artifacts\<jobid>\`
+3. `finally`: `Remove-BuildVM.ps1` — stop VM + rimozione directory clone
+
+### Caso d'uso implementato e testato
+- Repo: `Simone/nsis-plugin-nsinnounp` (NSIS plugin C++ — MSBuild)
+- Build command: `python build_plugin.py --final --dist-dir dist`
+- 4 configurazioni parallele: x86-unicode, x64-unicode, cli-x86, cli-x64
+- Artifact: `dist/x86-unicode/nsInnoUnp.dll`, `dist/amd64-unicode/nsInnoUnp.dll`, `dist/nsInnoUnpCLI.exe`, `dist/nsInnoUnpCLI64.exe`
+- e2e-009: SUCCESS in 02:09, cleanup automatico confermato
+
+### Fix critici applicati durante sviluppo
+- **TRK0002 Windows quota exhaustion**: `build_plugin.py` divide thread count per numero di build parallele
+- **MSBuild detection per VS 2026**: fix in `build_plugin.py` per vswhere con VS 2026 BuildTools
+- **Output filter nascondeva errori**: filtro cambiato da substring a prefix match
+- **--dist-dir**: nuovo flag per raccogliere artifact in cartella piatta pre-clean
+- **--no-clean / --no-copy**: flag CI-friendly per skip cleanup e skip copia verso plugins dir
@@ -4,9 +4,15 @@ Date: 2026-05-10

 ## Archived Files

-### Setup-GiteaSSH.md
-**Reason**: Obsolete — current workflow uses HTTP URLs + credential manager for Gitea access, not SSH key-based authentication.
-**When to revisit**: If SSH-based Git clones become necessary (e.g., for server-to-server scenarios).
+### PLAN.md (archived 2026-05-10)
+**Reason**: Pianificazione iniziale (ultimo update 2026-05-08) superata dallo stato post Sprint 8.
+Stato corrente del sistema, decisioni tecniche e roadmap sono ora distribuiti tra:
+- `TODO.md` (root) per audit trail, summary status e backlog
+- `docs/ARCHITECTURE.md` per il design del sistema
+- `docs/CI-FLOW.md` per il flusso operativo
+- `docs/RUNBOOK.md` per il triage incident
+
+Resta come riferimento storico.

 ### TEST-7.4-e2e.md
 **Reason**: Sprint 7.4 refactor validation document. Specific to §7.4 Deploy↔Setup refactor completion testing.
@@ -16,6 +22,13 @@ Date: 2026-05-10
 - Post-refactor sign-off checklist
 **Useful for**: §6.6 (Toolchain Tier-1) template updates, Linux template setup (§6.1)

+## De-archived
+
+### Setup-GiteaSSH.md (restored 2026-05-10)
+Originariamente archiviato come "obsolete (HTTP+credential manager)" ma di fatto il workflow
+live (`gitea/workflows/build-nsis.yml`) e `Setup-Host.ps1` continuano a usare l'alias SSH
+`gitea-ci` (porta 2222) per i clone Git. Ripristinato in `docs/Setup-GiteaSSH.md`.
+
 ## Active Documentation

 All current, operational docs remain in parent directory:
@@ -24,7 +37,8 @@ All current, operational docs remain in parent directory:
 - CI-FLOW.md
 - HOST-SETUP.md
 - WINDOWS-TEMPLATE-SETUP.md
+- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
 - OPTIMIZATION.md
 - RUNBOOK.md
 - TEST-PLAN-v1.3-to-HEAD.md
- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
+- Setup-GiteaSSH.md
@@ -1,101 +0,0 @@
-# Configurazione accesso SSH a Gitea
-
-**Target**: clone da `git@gitea.emulab.it:Simone/nsis-plugin-nsinnounp.git`  
-**Gitea**: `http://10.10.20.11:3100` / `https://gitea.emulab.it`
-
---
-
-## 1. Genera la chiave SSH sull'host Windows
-
-```powershell
-# Da PowerShell normale (non admin necessario)
-ssh-keygen -t ed25519 -C "ci-build@WS1-W11" -f "$env:USERPROFILE\.ssh\id_ci_gitea"
-```
-
- Passphrase: **lascia vuota** (il CI gira non-interattivo)
- Produce due file:
-  - `~\.ssh\id_ci_gitea` — chiave privata (non condividere mai)
-  - `~\.ssh\id_ci_gitea.pub` — chiave pubblica da aggiungere a Gitea
-
---
-
-## 2. Aggiungi la chiave pubblica a Gitea
-
-1. Apri `http://10.10.20.11:3100` → Login come **Simone**
-2. Menu utente (in alto a destra) → **Settings** → **SSH / GPG Keys**
-3. Clicca **Add Key**
-4. Incolla il contenuto di `~\.ssh\id_ci_gitea.pub`:
-
-```powershell
-Get-Content "$env:USERPROFILE\.ssh\id_ci_gitea.pub" | clip
-```
-
-5. **Key Name**: `WS1-CI-Host`
-6. Salva → **Add Key**
-
---
-
-## 3. Configura SSH client sull'host
-
-> **Attenzione**: `10.10.20.11` è già usato nel file `~\.ssh\config` con `User root` (entry `HomeAssistant`).
-> Non usare `Host 10.10.20.11` direttamente — usare un alias dedicato `gitea-ci`.
-
-Aggiungi in fondo a `~\.ssh\config`:
-
-```powershell
-$entry = @"
-
-Host gitea-ci
-    HostName 10.10.20.11
-    Port 2222
-    User git
-    IdentityFile $env:USERPROFILE\.ssh\id_ci_gitea
-    IdentitiesOnly yes
-"@
-Add-Content "$env:USERPROFILE\.ssh\config" $entry
-```
-
---
-
-## 4. Verifica connessione
-
-```powershell
-ssh -T gitea-ci
-```
-
-Risposta attesa:
-```
-Hi there, Simone! You've successfully authenticated with the key named ci-build@WS1-W11, but Gitea does not provide shell access.
-```
-
-> **Nota**: exit code 1 è **normale** — Gitea non fornisce shell, ma l'autenticazione è avvenuta.
-
---
-
-## 5. ~~Trova la porta SSH di Gitea~~
-
-**Porta confermata: 2222** (verificata con `Test-NetConnection -ComputerName 10.10.20.11 -Port 2222`).
-
---
-
-## 6. URL SSH da usare in Invoke-CIJob.ps1
-
-Usare l'alias `gitea-ci` definito in `~\.ssh\config`:
-
-```powershell
-RepoUrl 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git'
-```
-
-Oppure con IP/porta espliciti (equivalente):
-
-```powershell
-RepoUrl 'ssh://git@10.10.20.11:2222/Simone/nsis-plugin-nsinnounp.git'
-```
-
---
-
-## 7. Aggiungi host a known_hosts (evita prompt interattivo)
-
-```powershell
-ssh-keyscan -p 2222 10.10.20.11 >> "$env:USERPROFILE\.ssh\known_hosts"
-```