local-ci-cd-system/AGENTS.md

AGENTS.md — Environment Reference

Questo file descrive l'ambiente su cui e' costruito il progetto. Leggerlo prima di generare o modificare qualsiasi script.

Istruzione per gli agenti: questo file va tenuto aggiornato. Se durante il lavoro si scopre un errore nuovo, un vincolo non documentato, un pattern che ha causato problemi o una best-practice utile, aggiungerla nella sezione "Errori frequenti da evitare" o in una sezione apposita. Non aggiungere dettagli ovvi o gia' coperti; solo informazioni che impedirebbero errori concreti in sessioni future.

---

Host

Parametro	Valore
OS	Windows 11
Hardware	i9-10900X, 64 GB RAM, NVMe SSD
PowerShell	5.1 (Windows PowerShell — NON Core/7)
VMware Workstation	Pro, vmrun.exe in C:\Program Files (x86)\VMware\VMware Workstation\
SSH client	ssh.exe / scp.exe built-in Windows 11 (PATH)
act_runner	v1.0.2 — F:\CI\act_runner\act_runner.exe
Gitea	http://10.10.20.11:3100 / https://gitea.emulab.it

---

PowerShell 5.1 — Vincoli critici

Tutti gli script devono girare su Windows PowerShell 5.1. Le seguenti sintassi sono disponibili solo in PS 7+ e NON vanno usate:

Costrutto PS 7+	Alternativa PS 5.1 corretta
$x ??= 'default'	if ($null -eq $x) { $x = 'default' }
$a ?? $b	if ($null -ne $a) { $a } else { $b }
cmd1 && cmd2	cmd1; if ($LASTEXITCODE -eq 0) { cmd2 }
cmd1 || cmd2	cmd1; if ($LASTEXITCODE -ne 0) { cmd2 }
$x is [int]	$x -is [int]
Ternary $a ? $b : $c	if ($a) { $b } else { $c }
foreach-object con &&	pipeline classico con -ErrorAction Stop

Ogni script deve avere in testa:

#Requires -Version 5.1
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

---

Python development

L'orchestratore CI vive in src/ci_orchestrator/ (package ci-orchestrator, entry point python -m ci_orchestrator). Tutta la logica applicativa nuova va scritta in Python, non in PowerShell. Gli script PS in scripts/ sono ridotti a shim a 3 righe verso la CLI Python e sono mantenuti solo per compatibilita' con Task Scheduler e caller esterni.

Parametro	Valore
Python	3.11+ richiesto (requires-python in pyproject.toml)
Venv produzione	F:\CI\python\venv\ — install non-editable: pip install . (act_runner=LocalSystem; -e rompe con No module named ci_orchestrator). Ri-deploy a ogni modifica codice.
Venv dev locale	.venv\ (NON committare; gitignored)
Install (dev locale)	python -m pip install -e .[dev] — editable solo nel .venv dev
Test	python -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=90
Lint	python -m ruff check src tests\python
Type-check	python -m mypy --strict src

Convenzioni Python (enforced da ruff + mypy --strict):

• Type hints obbligatori su funzioni pubbliche e helper esportati. Evitare Any se esiste un tipo concreto/Protocol; Any solo per fixture pytest e mock.
• Niente variabili globali. Lo state vive in oggetti passati esplicitamente (factory backends.load_backend(config), Config dataclass).
• Niente print(): usare click.echo (rispetta il flag -q di click e il redirect err=True per stderr).
• Niente subprocess.run(..., shell=True). Niente shell-out per cose che esistono come libreria Python (paramiko per SSH, pypsrp per WinRM, keyring per credenziali).
• Encoding stdio sempre UTF-8: i moduli Python lo assumono e runner/config.yaml esporta PYTHONIOENCODING=utf-8 ad act_runner.

Mappatura script PowerShell → sotto-comando Python (Fase A2/A3/A4 + C). I .ps1 qui sotto sono archiviati in scripts/archived/ (congelati, esenti da lint, nessun caller vivo — l'action Gitea chiama Python direttamente). Non chiamarli né estenderli; vedi scripts/archived/README.md.

PowerShell archiviato	Python sub-command
Wait-VMReady.ps1	python -m ci_orchestrator wait-ready
New-BuildVM.ps1	python -m ci_orchestrator vm new
Remove-BuildVM.ps1	python -m ci_orchestrator vm remove
Cleanup-OrphanedBuildVMs.ps1	python -m ci_orchestrator vm cleanup
Invoke-RemoteBuild.ps1	python -m ci_orchestrator build run
Get-BuildArtifacts.ps1	python -m ci_orchestrator artifacts collect
Watch-DiskSpace.ps1	python -m ci_orchestrator monitor disk
Watch-RunnerHealth.ps1	python -m ci_orchestrator monitor runner
Get-CIJobSummary.ps1	python -m ci_orchestrator report job
Invoke-CIJob.ps1	python -m ci_orchestrator job
Start-BurnInTest.ps1 / -Linux	python -m ci_orchestrator bench run
Test-CapacityBurnIn.ps1	python -m ci_orchestrator bench run
Test-Smoke.ps1	python -m ci_orchestrator smoke run
Validate-HostState.ps1	python -m ci_orchestrator validate host
Set-CIGuestCredential.ps1	python -m ci_orchestrator creds set

Restano in PowerShell (girano sull'host Windows fuori dal flusso CI o nel guest, non ancora portati): Setup-Host.ps1, scripts/Register-CIScheduledTasks.ps1, scripts/Backup-CITemplate.ps1, scripts/Invoke-RetentionPolicy.ps1, scripts/Set-TemplateSharedFolders.ps1, scripts/Test-CIGuestWinRM.ps1, gli harness e2e scripts/Test-E2E-Section3.3.ps1 / Test-Ns7zipBuild-Linux.ps1 / Test-NsinnounpBuild*.ps1, tutti i template/Deploy-*.ps1, template/Prepare-*.ps1, template/Install-CIToolchain-*.ps1.

Test gate: coverage totale ≥90% (alzato in A5, poi a 90%). Nuovi moduli devono includere unit test con mock; gli errori frequenti di questa stessa sezione sono coperti da tests/python/test_agents_errors.py come regression test — non rimuoverli senza aggiornare la voce in "Errori frequenti da evitare" e motivare la rimozione.

Closeout fasi A: vedi plans/A1-closeout.md, plans/A2-closeout.md, plans/A3-closeout.md, plans/A4-closeout.md, plans/A5-closeout.md per stato per-fase, decisioni prese e voci pendenti a carico utente.

---

Struttura directory host (fissa)

F:\CI\
  act_runner\          — binario e stato act_runner
  Templates\
    WinBuild2025\      — template Windows Server 2025
    WinBuild2022\      — template Windows Server 2022
    LinuxBuild2404\    — template Ubuntu 24.04
  BuildVMs\            — clone efimeri (creati/distrutti per ogni job)
  Artifacts\           — artifact raccolti (per job-id)
  ISO\                 — ISO/VMDK di bootstrap (cache download)
  keys\
    ci_linux           — chiave SSH privata per guest Linux (no passphrase)
    ci_linux.pub       — chiave pubblica corrispondente

---

VM Template

Windows (WinBuild2025 — primario)

Parametro	Valore
OS	Windows Server 2025
VMX	F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
Snapshot clone	BaseClean
Transport	WinRM HTTPS porta 5986, cert self-signed (lab-only)
Credenziali	Windows Credential Manager target BuildVMGuest
Rete	VMnet8 NAT — 192.168.79.0/24
Toolchain	VS Build Tools 2026 (MSBuild 18.5 / v145), .NET SDK 10, Python 3.13, Git, 7-Zip

Variante WinBuild2022: path F:\CI\Templates\WinBuild2022\WinBuild2022.vmx, stesso snapshot BaseClean.

Linux (LinuxBuild2404)

Parametro	Valore
OS	Ubuntu 24.04 LTS (cloud image)
VMX	F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
Snapshot clone	BaseClean-Linux
Transport	SSH porta 22, utente ci_build, chiave F:\CI\keys\ci_linux
Rete	VMnet8 NAT — 192.168.79.0/24
Toolchain	GCC, G++, Clang, CMake, Ninja, Python 3, Git, 7-Zip
CI dirs	/opt/ci/{build,output,scripts,cache} — owner ci_build

Linux Rust (LinuxRust2404)

Variante di LinuxBuild2404 per workspace Rust (es. app Tauri): stessa cloud image e stesso layout guest, provisioning via template/Install-CIToolchain-LinuxRust2404.sh che aggiunge le librerie webview/GTK di Tauri v2 e una toolchain Rust system-wide sotto /opt/rust (rustup + rustfmt + clippy + binario cargo-audit; il DB advisory di cargo-audit NON e' bakato, viene fetchato a runtime).

Parametro	Valore
OS	Ubuntu 24.04 LTS (cloud image)
VMX	LinuxRust2404/LinuxRust2404.vmx (sotto la dir templates)
Snapshot clone	BaseClean-LinuxRust
Transport	SSH porta 22, utente ci_build, stessa chiave di LinuxBuild2404
Toolchain	quella di LinuxBuild2404 + webview/GTK Tauri + Rust in /opt/rust
Comandi	ci template deploy-rust / ci template prepare-rust

--rust-channel (default stable) controlla la toolchain bakata: pinnare una versione esatta (es. 1.97.1) per uno snapshot deterministico; con stable rustup riscarica a runtime ad ogni nuova stable. Rigenerare lo snapshot quando cambia il pin o la baseline apt di sicurezza.

Due vincoli sull'albero /opt/rust, entrambi regressioni gia' occorse:

1. chown DOPO l'installazione. Lo script gira come root, quindi tutto cio' che rustup/cargo creano nasce root-owned: un chown fatto solo prima copre le due directory vuote e nient'altro. Senza il chown finale ci_build non puo' scrivere ne' in RUSTUP_HOME ne' in CARGO_HOME/registry, e ogni build Rust con dipendenze esterne muore con Permission denied (os error 13). Gli assert devono verificare la scrivibilita' (sudo -u ci_build test -w), non solo test -x sui binari: altrimenti il template rotto passa la sua build e fallisce nei job dei consumatori.
2. /etc/profile.d da solo non basta. L'orchestratore esegue i comandi con paramiko exec_command + sh -c (transport/ssh.py, commands/build.py): shell non di login, profile.d non viene mai sorgiato. RUSTUP_HOME/CARGO_HOME vanno anche in /etc/environment (letto da pam_env all'apertura della sessione SSH) e i proxy rustup symlinkati in /usr/local/bin.

---

Transport layer

• Windows guest: WinRM (New-PSSession con New-CISessionOption da _Common.psm1). Usare Invoke-Command -Session, Copy-Item -ToSession / -FromSession.
• Linux guest: SSH/SCP via ssh.exe / scp.exe. Usare le funzioni di scripts/_Transport.psm1: Invoke-SshCommand, Copy-SshItem, Test-SshReady.
• vmrun.exe: sempre invocato tramite Invoke-Vmrun da _Common.psm1 (wrapper uniforme che gestisce $LASTEXITCODE e output).

NON modificare il branch WinRM esistente quando si lavora sul branch Linux e viceversa.

---

act_runner / Gitea Actions

• Labels runner: windows-build:host, linux-build:host
• Env vars iniettate in ogni job (da runner/config.yaml):
  • GITEA_CI_TEMPLATE_PATH — VMX Windows template
  • GITEA_CI_LINUX_TEMPLATE_PATH — VMX Linux template
  • GITEA_CI_CLONE_BASE_DIR — F:\CI\BuildVMs
  • GITEA_CI_ARTIFACT_DIR — F:\CI\Artifacts
  • GITEA_CI_GUEST_CRED_TARGET — BuildVMGuest
  • GITEA_CI_SSH_KEY_PATH — F:\CI\keys\ci_linux
  • CI_PYTHON_LAUNCHER — absolute path al Python di sistema usato per bootstrap del venv produzione (F:\CI\python\venv). act_runner gira come SYSTEM con PATH sanitizzato (no python/py.exe risolvibili), quindi i workflow Python leggono questo env come single source of truth. Aggiornare solo quando si fa upgrade dell'interprete.

---

Regole di stile (PSScriptAnalyzer)

Configurazione in PSScriptAnalyzerSettings.psd1. Regole principali:

• Indentazione: 4 spazi (no tab)
• Write-Host e' permesso (output catturato da act_runner; Write-Output interferisce con i return value)
• Invoke-Expression vietato
• Funzioni state-changing devono supportare -WhatIf / ShouldProcess
• Credenziali solo come [PSCredential], mai plain-text string
• Nessuna variabile globale ($global:)

---

Errori frequenti da evitare

1. Sintassi PS 7+ in script PS 5.1 — vedi tabella sopra.

2. $LASTEXITCODE non controllato dopo vmrun, ssh, scp — controllare sempre e fare throw se non zero.

3. Percorsi hardcoded senza parametro — ogni path critico deve avere un parametro con default documentato.

4. Modificare entrambi i branch (WinRM e SSH) nello stesso script — mantenerli separati con if ($GuestOS -eq 'Linux').

5. Usare New-PSSession / WinRM verso host Linux — Linux usa solo SSH tramite _Transport.psm1.

6. Non rimuovere il seed ISO dal VMX dopo il primo boot Linux — ide1:0.present = "FALSE" deve essere settato dopo cloud-init.

7. [ordered]@{} non disponibile in PS 2 — non e' un problema qui (PS 5.1), ma ricordare che [ordered] e' PS 3+.

8. ForEach-Object -Parallel — disponibile solo in PS 7+; usare foreach classico o Start-Job.

9. Snapshot template catturato con VM accesa — produce file *.vmem / *.vmsn con memoria; vmrun clone ... linked -snapshot=<name> rifiuta con Error: The virtual machine should not be powered on. It is already running. anche se vmrun list mostra 0 VM. Catturare snapshot SOLO da stato fully powered-off (verificare assenza di .vmem nella dir template).

10. vmrun getGuestIPAddress per check "VM running" — richiede VMware Tools attivi nel guest; in headless Tools puo' impiegare 30-60s a rispondere e il check appare bloccato. Usare vmrun list e cercare il path del VMX nell'output per is_running. Per recuperare l'IP usare getGuestIPAddress -wait (blocca internamente finché Tools registrano l'IP) e filtrare le righe che iniziano con "Error:" perché vmrun in modalità headless può tornare exit code 0 con "Error: The VMware Tools are not running..." su stdout invece di usare un exit code non-zero.

11. Machine-id identico tra clone Linux — le cloud image Ubuntu hanno un /etc/machine-id fisso. VMware DHCP assegna l'IP tramite DHCP client-id derivato da machine-id: se tutti i clone hanno lo stesso machine-id ottengono lo stesso IP e si bloccano per "IP collision". Fix nel template (prima di prendere lo snapshot): sudo truncate -s 0 /etc/machine-id && sudo rm -f /var/lib/dbus/machine-id && sudo shutdown -h now, poi ricreare lo snapshot BaseClean-Linux da stato powered-off.

12. & nativecmd 2>$null NON sopprime stderr in PS 5.1 con $ErrorActionPreference='Stop' — la stderr del processo nativo viene convertita in ErrorRecord nel pipeline di PowerShell; sotto 'Stop' questo diventa un errore terminante PRIMA che 2>$null possa scartarlo. Esempio: ssh-keygen -R <ip> -f <file> stampa "Host X not found in file" su stderr → eccezione terminante. Fix: usare $ErrorActionPreference = 'SilentlyContinue' attorno alla chiamata oppure 2>&1 | Out-Null. Per i job CI su VM ephemere locali, usare direttamente StrictHostKeyChecking=no UserKnownHostsFile=NUL (default in _Transport.psm1 con KnownHostsFile='') — nessun ssh-keygen necessario.

13. Quote WinRM/desktop-heap troppo basse per builds Windows paralleli — sintomo: MSBuild error MSB6003: CL.exe could not be run. System.ComponentModel.Win32Exception (0x80004005): Not enough quota is available to process this command (oppure le altre tool MSVC: link.exe, mt.exe) quando il build interno fa fan-out parallelo (es. matrix x86/x64/x86-ansi, MSBuild /maxcpucount). Causa: il plugin endpoint Microsoft.PowerShell del guest ha MaxMemoryPerShellMB=150 di default e l'heap del desktop non-interattivo (Session 0) ha SharedSection 3rd field=768 KB — entrambi insufficienti per più CL.exe concorrenti via WinRM. Non emerge in pre-migration Win→Win perché Invoke-Command su PSSession localhost-style eredita quote più larghe; emerge appena il path passa per pypsrp Linux→Win. Fix nel template (Deploy-WinBuild2025.ps1 / 2022 lo fa, Install-CIToolchain lo valida): Set-Item WSMan:\localhost\Plugin\Microsoft.PowerShell\Quotas\MaxMemoryPerShellMB 2048, Set-Item WSMan:\localhost\Shell\MaxProcessesPerShell 100, registry HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows patch del 3° campo SharedSection a 4096, reboot (csrss legge SharedSection solo al boot), nuovo BaseClean. Dettagli e procedura completa in docs/WINDOWS-TEMPLATE-SETUP.md § "WinRM quotas e desktop heap".

14. deploy-* --force lanciato mentre la VM target è ACCESA — corrompe la VM in esecuzione e produce un timeout allo Step 7 che sembra un problema di rete. Occorso il 2026-07-22 su LinuxRust2404, con un prepare-rust ancora in corso sulla stessa VMX. Meccanica: (a) Step 1 vede <disk>.vmdk.lck e lo cancella come "stale artifact" — non era stale, apparteneva al processo vivo; (b) Step 4 riscrive il VMDK base sotto il guest in esecuzione, che muore; (c) Step 6 lancia il power-on, il nuovo vmware-vmx muore subito perché la VMX è già occupata, ma il controllo [OK] VM appears in vmrun list passa lo stesso perché vede l'istanza vecchia; (d) Step 7 interroga per 10 minuti un guest morto e riporta Error: The VMware Tools are not running in the virtual machine. Diagnosi in 5 secondi: ps -eo pid,lstart,etime,args | grep vmware-vmx — se il vmware-vmx vivo è più vecchio del deploy appena lanciato, è questo il caso. Recupero: vmrun stop <vmx> hard, rimuovere i delta orfani <disk>-00000*.vmdk, verificare vmrun list = 0, poi rilanciare. Non interpretarlo come DHCP incastrato (vedi #15) e non risolverlo con un retry automatico: riavviare una VM già corrotta ripete il fallimento con la causa ormai illeggibile.

15. Step 7 in timeout: distinguere tre cause diverse che danno lo stesso messaggio — getGuestIPAddress risponde The VMware Tools are not running sia quando il guest non ha IP, sia quando ha l'IP ma i Tools non rispondono. Ordine di verifica, dal più veloce: (a) collisione — ps | grep vmware-vmx, processo più vecchio del deploy corrente → vedi #14; (b) DHCP host incastrato — ip -4 addr show vmnet8 deve dare 192.168.79.1/24 e ps -ef | grep vmnet-dhcpd deve mostrarlo vivo; se no, sudo systemctl restart vmware-networks (o vmware-host.service); (c) guest senza lease o Tools non pronti — cercare il MAC della VMX in /etc/vmware/vmnet8/dhcpd/dhcpd.leases e in ip neigh show dev vmnet8: se un lease c'è, il guest è vivo e mancano solo i Tools, quindi sondare TCP/22 direttamente invece di aspettare getGuestIPAddress.

16. Delta di snapshot orfani dopo --force — deploy-* cancella <vm>.vmsd (il database snapshot) per evitare l'errore di resize sulla catena, ma non cancella i file delta <disk>-00000N.vmdk. Restano su disco con un parentCID che non corrisponde più al base ricreato: innocui (fuori dal percorso di boot, la VMX punta al base con parentCID=ffffffff) ma confondono la diagnosi e vanno rimossi a mano. Verifica della catena: head -c 2000 <disk>.vmdk | strings | grep -E '^CID|parentCID'.

17. vmrun list è per-utente e mente se lo lanci con l'utente sbagliato — le VM della CI le avvia ci-runner; vmrun -T ws list eseguito come simone (o come root) risponde Total running VMs: 0 anche mentre un clone sta girando, perché vede solo l'istanza VMware dell'utente corrente. Occorso il 2026-07-22 durante la validazione della cache cargo: vmrun list diceva 0 e ps mostrava un vmware-vmx vivo da 19 minuti. Conseguenza pratica: il check "0 VM accese" prima di un deploy --force (vedi #14) non è affidabile se non lo si esegue come ci-runner. Usare sudo -u ci-runner vmrun -T ws list, oppure — meglio, perché indipendente dall'utente — ps -eo pid,lstart,etime,args | grep '[v]mware-vmx', che è anche la diagnosi già raccomandata in #14 e #15.

18. Gitea è dietro Cloudflare: Python-urllib riceve 403 prima di arrivare a Gitea — qualunque chiamata a https://gitea.emulab.it/api/v1/... fatta con urllib.request senza User-Agent esplicito torna 403 con body error code: 1010 (Cloudflare "browser banned"), su ogni endpoint, incluso /api/v1/version che non richiede autenticazione. Sembra identico a un problema di token/scope e manda la diagnosi fuori strada. Verifica in due mosse: curl -s https://gitea.emulab.it/api/v1/version risponde 200 (curl manda il suo UA) mentre la stessa chiamata in Python risponde 403; gli header di risposta mostrano server: cloudflare + cf-ray. Fix: header User-Agent esplicito — qualunque stringa normale passa (vedi operations/executions.py::_USER_AGENT). Corollario generale: quando un endpoint HTTP risponde 4xx, leggere il body prima di ipotizzare la causa — Gitea scrive il permesso mancante (required=[read:user], token scope=read:admin,read:repository), Cloudflare scrive il suo codice.