# Fase A — Checklist finale per l'utente

La Fase A è **code-complete e pushata** sul branch `feature/python-rewrite-and-linux-migration`.
Restano solo le validazioni che richiedono accesso fisico all'host CI con VMware
Workstation, snapshot template attivi e act_runner registrato.

Questo documento elenca i passi da eseguire in ordine, con checklist e comandi
copiabili. Stop a primo errore: ogni passo è un gate per il successivo.

> **Tempo stimato totale**: 1–2 ore (escluse build lunghe nel passo 5).

---

## Passo 1 — Aggiornare il venv di produzione sull'host CI

Il codice nuovo va installato nel venv che act_runner usa
(`F:\CI\python\venv\`).

- [x] Aprire PowerShell **come amministratore** sull'host CI.
- [x] Posizionarsi nella copia git aggiornata del repo (pull del branch
      `feature/python-rewrite-and-linux-migration`):

  ```powershell
  cd <path-locale-repo>
  git fetch origin
  git checkout feature/python-rewrite-and-linux-migration
  git pull
  ```

- [x] Installare il package nel venv di produzione (**non editable**):

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m pip install .
  ```

  > ⚠️ **Non usare `pip install -e .` su questo host.** act_runner gira
  > come `LocalSystem`. Un install editable scrive un `.pth` verso la
  > sorgente; se il `cd` era in una dir di lavoro di act_runner
  > (`F:\CI\RunnerWork\<hash>\hostexecutor`, transitoria) o sul drive
  > utente `N:` (non risolto da LocalSystem), il runner fallisce con
  > `No module named ci_orchestrator`. L'install regolare copia il
  > package in `site-packages` su `F:` (accessibile a LocalSystem).
  > Conseguenza: ogni modifica al codice richiede di ri-eseguire
  > `pip install .` — è uno step di deploy. Assicurarsi che il `cd` del
  > passo precedente punti alla copia git reale del repo, non a una dir
  > sotto `F:\CI\RunnerWork`.

- [x] Smoke check rapido che la CLI risponda:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator --help
  ```

  Atteso: lista degli 11 sub-comandi (`wait-ready`, `vm`, `build`,
  `artifacts`, `monitor`, `report`, `job`).

---

## Passo 2 — Riavviare act_runner

L'act_runner gira come servizio SYSTEM e legge `runner/config.yaml`
all'avvio. La modifica di A4 (`PYTHONIOENCODING=utf-8`) ha effetto solo
dopo restart.

- [x] Trovare il servizio:

  ```powershell
  Get-Service | Where-Object { $_.Name -like '*act*runner*' }
  ```

- [x] Restart (sostituisci `<NomeServizio>` con quello trovato):

  ```powershell
  Restart-Service -Name '<NomeServizio>'
  ```

- [x] Verificare che sia partito:

  ```powershell
  Get-Service -Name '<NomeServizio>'
  ```

  Atteso: `Status = Running`.

---

## Passo 3 — Smoke `wait-ready` su VM Windows reale

PoC pendente da A1.

- [x] Clonare manualmente un template Windows:

  ```powershell
  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws clone `
    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
    'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
    linked -snapshot=BaseClean -cloneName=smoke-win
  ```

- [x] Avviare la VM:

  ```powershell
  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws start 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' nogui
  ```

- [x] Eseguire `wait-ready`:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
    --guest-os windows --timeout 180
  ```

  Atteso: exit code `0` entro 3 minuti.

- [x] Cleanup VM di smoke:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' --force
  ```

---

## Passo 4 — Smoke `wait-ready` su VM Linux reale

Stesso schema, template Linux. PoC pendente da A1.

- [x] Clonare:

  ```powershell
  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws clone `
    'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
    'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
    linked -snapshot=BaseClean-Linux -cloneName=smoke-linux
  ```

- [x] Start + wait-ready:

  ```powershell
  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws start 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' nogui

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
    --guest-os linux --timeout 180
  ```

  Atteso: exit code `0`.

  > **Prerequisito scoperto**: `F:\CI\config.toml` deve esistere con `ssh_key_path`
  > impostato — altrimenti SSH fallisce con `No authentication methods available`.
  > Creato durante questa validazione; vedi HOST-SETUP.md step 6.

- [x] Cleanup:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' --force
  ```

---

## Passo 5 — Smoke end-to-end pipeline (`job`)

Valida A3+A4 insieme: clone → wait → build → collect → cleanup.

- [x] Lanciare un job sul template Windows con uno script trivial:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
    --template-path 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
    --snapshot-name BaseClean `
    --job-id smoke-job-win `
    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
    --branch main `
    --build-command 'echo hello > artifact.txt' `
    --guest-artifact-source 'artifact.txt' `
    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-win'
  ```

  Atteso: exit code `0`, file `F:\CI\Artifacts\smoke-job-win\artifact.txt` presente,
  VM smoke-job-win **non** più esistente in `F:\CI\BuildVMs\` (cleanup garantito).

- [x] Ripetere su Linux:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
    --template-path 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
    --snapshot-name BaseClean-Linux `
    --guest-os linux `
    --job-id smoke-job-linux `
    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
    --branch main `
    --build-command 'echo hello > artifact.txt' `
    --guest-artifact-source 'artifact.txt' `
    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-linux'
  ```

  Atteso: exit code `0`, `F:\CI\Artifacts\smoke-job-linux\smoke-job-linux\artifact.txt` presente.

- [x] Verificare assenza VM orfane:

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm cleanup --what-if
  ```

  Atteso: nessun candidato.

---

## Passo 6 — Workflow Gitea end-to-end

Validazione di A4 lato runner reale.

- [x] Aprire la UI Gitea, repo `local-ci-cd-system`, branch
      `feature/python-rewrite-and-linux-migration`.
- [~] Triggerare manualmente i 3 workflow (Actions → Run workflow):
  - [x] `lint.yml` → atteso PASS
  - [x] `self-test.yml` → atteso PASS
  - [ ] `build-nsInnoUnp.yml` matrix Win+Linux → atteso PASS,
        artifact pubblicato per entrambe le piattaforme.

- [ ] Se uno fallisce: scaricare i log dell'esecuzione, aprire issue in
      `TODO.md` con sha del workflow run e output errore.

---

## Passo 7 — Burn-in capacità (4 job concorrenti)

Validazione finale di A5 (definizione di "fatto Fase A").

- [ ] Triggerare il workflow `build-nsInnoUnp.yml` 4 volte di seguito
      (oppure usare lo script `scripts/Test-CapacityBurnIn.ps1` che ora
      delega via shim alla CLI Python `job`):

  ```powershell
  .\scripts\Test-CapacityBurnIn.ps1 -Concurrency 4 -Rounds 10
  ```

- [ ] Misurare:
  - [ ] Tutti i 40 job (4 × 10) PASS
  - [ ] Zero VM orfane in `F:\CI\BuildVMs\` a fine burn-in
  - [ ] Zero file lock orfani in `F:\CI\BuildVMs\*.lock`
  - [ ] Spazio disco libero non scende sotto la soglia di
        `Watch-DiskSpace`

---

## Passo 8 — Benchmark wall-clock

Confronto Python vs PowerShell. Pendenza A4.

- [ ] Eseguire prima del merge:

  ```powershell
  .\scripts\Measure-CIBenchmark.ps1
  ```

  Annotare il tempo medio per job.

- [ ] Confrontare con il baseline pre-Python (se disponibile in
      `docs/OPTIMIZATION.md` o in un commit precedente). Tolleranza
      target: **±10%**.

- [ ] Se delta > 10%: aprire issue in `TODO.md` con dettagli per
      profiling. NON è bloccante per il merge della Fase A.

---

## Passo 9 — Merge della Fase A in `main`

Solo dopo che i passi 3–7 sono tutti `[x]` PASS.

- [ ] Aprire PR su Gitea: `feature/python-rewrite-and-linux-migration` → `main`.
- [ ] Verificare diff atteso: ~20 file Python nuovi sotto
      `src/ci_orchestrator/`, ~10 shim PS in `scripts/`, doc in
      `plans/A*-closeout.md`, AGENTS.md/ARCHITECTURE.md/README.md
      aggiornati.
- [ ] Self-review della PR: nessun secret, nessun path hardcodato fuori
      da `config.py`, nessun `.venv/` committato.
- [ ] Merge (squash sconsigliato — preserva la storia per-fase).
- [ ] Tag release: `git tag v2.0.0-phaseA` (o convenzione preferita).

---

## Tracciamento globale

| Passo | Descrizione                               | Stato |
| ----- | ----------------------------------------- | ----- |
| 1     | Aggiorna venv di produzione               | [x]   |
| 2     | Restart act_runner                        | [x]   |
| 3     | Smoke `wait-ready` Windows                | [x]   |
| 4     | Smoke `wait-ready` Linux                  | [x]   |
| 5     | Smoke `job` end-to-end (Win + Linux)      | [x]   |
| 6     | Workflow Gitea (lint + self-test + build) | [ ]   |
| 7     | Burn-in 4 job × 10 round                  | [ ]   |
| 8     | Benchmark wall-clock                      | [ ]   |
| 9     | Merge PR e tag release                    | [ ]   |

Quando tutti i passi sono `[x]`, la Fase A è **definitivamente chiusa** e
si può aprire la Fase B (porting su host Linux).