# Fase A — Checklist finale per l'utente

La Fase A è **code-complete e pushata** sul branch `feature/python-rewrite-phase-a`.
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\`).

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

  ```powershell
  cd <path-locale-repo>
  git fetch origin
  git checkout feature/python-rewrite-phase-a
  git pull
  ```

- [ ] Installare il package in editable nel venv di produzione:

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

- [ ] 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.

- [ ] Trovare il servizio:

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

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

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

- [ ] 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.

- [ ] 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
  ```

- [ ] 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
  ```

- [ ] 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.

- [ ] 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.

- [ ] 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
  ```

- [ ] 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`.

- [ ] 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.

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

  ```powershell
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
    --template 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
    --snapshot BaseClean `
    --name smoke-job-win `
    --build-command 'echo hello > artifact.txt' `
    --artifact-source 'C:\ci\workspace\artifact.txt' `
    --artifact-dest '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).

- [ ] Ripetere su Linux (cambiare `--template`, `--snapshot`,
      `--build-command 'echo hello > artifact.txt'`,
      `--artifact-source '/opt/ci/build/artifact.txt'`).

- [ ] Verificare assenza VM orfane:

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

  Atteso: nessun candidato.

---

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

Validazione di A4 lato runner reale.

- [ ] Aprire la UI Gitea, repo `local-ci-cd-system`, branch
      `feature/python-rewrite-phase-a`.
- [ ] Triggerare manualmente i 3 workflow (Actions → Run workflow):
  - [ ] `lint.yml` → atteso PASS
  - [ ] `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-phase-a` → `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               | [ ]   |
| 2     | Restart act_runner                        | [ ]   |
| 3     | Smoke `wait-ready` Windows                | [ ]   |
| 4     | Smoke `wait-ready` Linux                  | [ ]   |
| 5     | Smoke `job` end-to-end (Win + Linux)      | [ ]   |
| 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).