docs(a5): document Python orchestrator in AGENTS.md, ARCHITECTURE.md, README.md

AGENTS.md: new 'Python development' section (venv paths, install/lint/typecheck/test commands, conventions, full PS->Python sub-command mapping, list of PS scripts that stay PowerShell, link to phase closeouts). README.md: expand 'Python orchestrator' with examples for all 10 sub-commands (wait-ready, vm new/remove/cleanup, build run, artifacts collect, monitor disk/runner, report job, job), local validation gates with 80% coverage gate, link to test_agents_errors.py. docs/ARCHITECTURE.md: new 'Python orchestrator (Phase A)' section with package layout tree, VmBackend Protocol contract, load_backend(config) factory, Phase C ESXi extension recipe, transport selection note, and CI validation gates.
2026-05-14 17:38:10 +02:00
parent 5459672b42
commit 4d9c6d07ba
3 changed files with 255 additions and 13 deletions
@@ -51,6 +51,73 @@ $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\` (interprete `F:\CI\python\venv\Scripts\python.exe`)              |
+| Venv dev locale          | `.venv\` (NON committare; gitignored)                                                  |
+| Install editable         | `python -m pip install -e .[dev]`                                                     |
+| Test                     | `python -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=80`          |
+| 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):
+
+| PowerShell legacy (shim)            | 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`            |
+
+Restano in PowerShell (girano sull'host fuori dal flusso CI o nel guest):
+`Setup-Host.ps1`, `Register-CIScheduledTasks.ps1`, `Backup-CITemplate.ps1`,
+`Invoke-RetentionPolicy.ps1`, `Measure-CIBenchmark.ps1`,
+`Test-CapacityBurnIn.ps1`, tutti i `template/Deploy-*.ps1`,
+`template/Prepare-*.ps1`, `template/Install-CIToolchain-*.ps1` e i
+`tests/Test-*.ps1` di smoke locale.
+
+**Test gate**: coverage totale ≥80% (alzato in A5). 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)

 ```