@noeva/analytics-core 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -3,7 +3,27 @@
 Le versioni del pacchetto che i repository dei progetti installano (ADR 0005). Prima di
 `analytics upgrade` si legge cosa cambia fra la versione installata e la nuova.
 
-## 0.5.1 — 12 novembre 2026
+## 0.5.3 — 14 novembre 2026
+
+- **`noeva-snapshot giro`**: un giro solo, senza la coda, per i server dove gira gia'
+  il worker NOEVA-ETL (ADR 0004, punto 4). Il processo lo
+  prende NOEVA-ETL e lancia questo con il connettore `processo-esterno`: log su stderr,
+  su stdout solo l'esito in JSON, exit code diverso da zero se non si e' pubblicato,
+  con il motivo nell'ultima riga di stderr. `noeva-snapshot` passa alla 0.3.0.
+- `installa.ps1 -ConNoevaEtl`: installa e verifica come sempre, fa il primo giro con
+  `giro` e non registra l'attivita' pianificata (la toglie, se c'era da prima: due
+  worker si contenderebbero i processi del workspace). Con `-SoloControllo` controlla
+  che l'attivita' non ci sia.
+- Per averli serve un rilascio dell'eseguibile degli snapshot del progetto
+  (`rilascio-windows.yml`, `cosa=snapshot`).
+
+## 0.5.2 — 12 novembre 2026
+
+La 0.5.1 non e' mai arrivata sul registro (npm l'ha accettata e poi non l'ha resa
+disponibile): la 0.5.2 porta lo stesso contenuto, piu' il README del pacchetto senza il
+nome di un cliente e `test/nomi.test.js` che controlla anche README.md e package.json,
+che npm pubblica sempre.
+
 
 - Il servizio MCP dei PC (`noeva-<id>.exe`) non si blocca piu' su una query lenta
   (11/11/2026). Gli strumenti di Wren erano sincroni e giravano nell'event loop:

package/README.md

@@ -5,7 +5,7 @@ i moduli di pagina, gli strumenti dello snapshot, il kit dell'agente e il modell
 repository. La forma e' quella di `@noeva/etl-core` (noeva-etl, ADR-0093 e 0094).
 
 La fonte resta `lib/`: `prepara.js` ne copia in `contenuto/` (gitignorata) i file che il
-pacchetto porta, a ogni `npm pack` e a ogni prova. Questo README non va nel pacchetto.
+pacchetto porta, a ogni `npm pack` e a ogni prova. Questo README npm lo pubblica comunque, come la pagina del pacchetto.
 
 ```bash
 node lib/core/prepara.js && node --test lib/core/test/*.test.js   # le prove, anche in CI
@@ -13,9 +13,10 @@ cd lib/core && npm pack --dry-run                                  # cosa pubbli
 python3 lib/rilascio/estrai-progetto.py <id> <cartella vuota>      # un progetto nel suo repository
 ```
 
-- **Il pacchetto non nomina clienti**: `test/nomi.test.js` lo prova contro il registro.
-  Un commento in `lib/pagina` o `lib/snapshot` che cita un cliente arriva a tutti.
-- **La CI del repository nuovo puo' non partire**: con OIKI (6/11/2026) GitHub ha registrato
+- **Il pacchetto non nomina clienti**: `test/nomi.test.js` lo prova contro il registro, anche
+  su questo README, che npm pubblica sempre. Un commento in `lib/pagina` o `lib/snapshot`
+  che cita un cliente arriva a tutti.
+- **La CI del repository nuovo puo' non partire**: con il primo progetto estratto (6/11/2026) GitHub ha registrato
   `ci.yml`, arrivato col push che crea il repository, ma non partiva su push e PR, solo a mano.
   Si e' sbloccato al primo push di un commit che cambiava `ci.yml`, anche su un branch di
   prova poi cancellato. Dopo il primo push si controlla che la PR abbia il check `verifica`.

package/contenuto/lib/snapshot/ascolta.py

@@ -11,6 +11,9 @@ del worker noeva-etl; il server parla solo in uscita, verso NOEVA.
     noeva-snapshot ascolta --config worker.json              resta in ascolto (servizio)
     noeva-snapshot ascolta --config worker.json --una-volta  esegue cio' che c'e' in coda ed esce
                                                              (l'attivita' pianificata di Windows)
+    noeva-snapshot giro --config worker.json --pipeline <nome>
+                                    un giro solo, senza coda: lo lancia il worker NOEVA-ETL dove
+                                    il server ha anche altre pipeline ETL (vedi giro())
 
 La chiave NOEVA del worker sta in NOEVA_API_KEY, mai nel file: e' la chiave di un
 utente di servizio membro del workspace. worker.json (percorsi relativi al file):
@@ -25,6 +28,7 @@ quando c'e' un giro da fare.
 """
 from __future__ import annotations
 
+import contextlib
 import datetime as dt
 import json
 import os
@@ -122,39 +126,65 @@ def riassunto(report: dict | None) -> dict:
     }
 
 
+def cartella_del_giro(conf: dict, progetto: str, etichetta: str) -> pathlib.Path:
+    return conf["lavoro"] / progetto / f"{dt.datetime.now().strftime('%Y%m%dT%H%M%S')}-{etichetta[:8]}"
+
+
+def genera_e_pubblica(p: dict, conf: dict, chiave: str, workspace: str, cartella: pathlib.Path, *,
+                      esporta_fn=esporta_pacchetto, pubblica_fn=pubblica.pubblica_versione,
+                      biglietti_fn=pubblica.biglietto_dall_api, dopo_export=None) -> tuple[dict, dict | None]:
+    """Il cuore di un giro, con o senza coda: snapshot, biglietto, pubblicazione.
+    Restituisce l'esito e il report del giro; solleva se qualcosa non va (allora
+    non si e' pubblicato niente, o la pubblicazione e' a meta' e il puntatore no)."""
+    progetto = p["progetto"]
+    dati, report_path = cartella / "dati", cartella / "giro.json"
+    dati.mkdir(parents=True, exist_ok=True)
+    inizio = time.time()
+    esporta_fn(p["pacchetto"], p["connessione"], dati, report_path)
+    report = json.loads(report_path.read_text(encoding="utf-8")) if report_path.is_file() else None
+    if dopo_export:
+        dopo_export()
+    da = f"{socket.gethostname()} noeva-snapshot"
+    esito = pubblica_fn(
+        progetto, dati, conf["contenitore"].rstrip("/"),
+        lambda versione: biglietti_fn(conf["api"], chiave, workspace, progetto, versione, da),
+        stampa=log)
+    uscita = {
+        "progetto": progetto, "versione": esito["versione"], "data_del_dato": esito.get("data_del_dato"),
+        "file": len(esito.get("file", [])), "byte": esito.get("byte"),
+        "secondi": round(time.time() - inizio, 1), **riassunto(report),
+    }
+    return uscita, report
+
+
+def report_dalla_cartella(cartella: pathlib.Path) -> dict | None:
+    """Il report di un giro fallito, se l'export e' arrivato a scriverlo."""
+    f = cartella / "giro.json"
+    try:
+        return json.loads(f.read_text(encoding="utf-8")) if f.is_file() else None
+    except ValueError:
+        return None
+
+
 def esegui(lavoro: dict, conf: dict, api: ApiNoeva, *, esporta_fn=esporta_pacchetto,
            pubblica_fn=pubblica.pubblica_versione, biglietti_fn=pubblica.biglietto_dall_api) -> bool:
-    """Un giro: snapshot, biglietto, pubblicazione, esito sul processo. True se pubblicato."""
+    """Un giro preso dalla coda: snapshot, biglietto, pubblicazione, esito sul processo. True se pubblicato."""
     processo, pipeline = lavoro["processId"], lavoro["pipeline"]
     p = conf["pipeline"][pipeline]
     progetto = p["progetto"]
-    cartella = conf["lavoro"] / progetto / f"{dt.datetime.now().strftime('%Y%m%dT%H%M%S')}-{processo[:8]}"
-    dati, report_path = cartella / "dati", cartella / "giro.json"
-    dati.mkdir(parents=True, exist_ok=True)
+    cartella = cartella_del_giro(conf, progetto, processo)
     log(f"{pipeline}: processo {processo}, giro in {cartella}")
     inizio = time.time()
-    report = None
     try:
         api.avanza(processo, status="running", progress=5)
-        esporta_fn(p["pacchetto"], p["connessione"], dati, report_path)
-        report = json.loads(report_path.read_text(encoding="utf-8")) if report_path.is_file() else None
-        api.avanza(processo, status="running", progress=70)
-
-        da = f"{socket.gethostname()} noeva-snapshot"
-        esito = pubblica_fn(
-            progetto, dati, conf["contenitore"].rstrip("/"),
-            lambda versione: biglietti_fn(conf["api"], api.chiave, api.workspace, progetto, versione, da),
-            stampa=log)
-        uscita = {
-            "progetto": progetto, "versione": esito["versione"], "data_del_dato": esito.get("data_del_dato"),
-            "file": len(esito.get("file", [])), "byte": esito.get("byte"),
-            "secondi": round(time.time() - inizio, 1), **riassunto(report),
-        }
+        uscita, report = genera_e_pubblica(
+            p, conf, api.chiave, api.workspace, cartella, esporta_fn=esporta_fn, pubblica_fn=pubblica_fn,
+            biglietti_fn=biglietti_fn, dopo_export=lambda: api.avanza(processo, status="running", progress=70))
         testo_report = json.dumps(report, default=str) if report else ""
         if report and len(testo_report) <= MAX_REPORT_BYTE:
             uscita["giro"] = report
         api.avanza(processo, status="completed", progress=100, outputData=uscita, completedAt=adesso())
-        log(f"{pipeline}: pubblicata {esito['versione']} in {uscita['secondi']}s")
+        log(f"{pipeline}: pubblicata {uscita['versione']} in {uscita['secondi']}s")
         return True
     except (Exception, SystemExit) as e:  # noqa: BLE001 - qualunque errore chiude il processo come fallito
         messaggio = str(e).strip() or e.__class__.__name__
@@ -162,7 +192,7 @@ def esegui(lavoro: dict, conf: dict, api: ApiNoeva, *, esporta_fn=esporta_pacche
         try:
             api.avanza(processo, status="failed", errorMessage=messaggio[:2000],
                        outputData={"progetto": progetto, "secondi": round(time.time() - inizio, 1),
-                                   **riassunto(report)},
+                                   **riassunto(report_dalla_cartella(cartella))},
                        completedAt=adesso())
         except Exception as e2:  # noqa: BLE001 - l'API giu': il processo resta running, lo si vede da NOEVA
             log(f"{pipeline}: non riesco a scrivere l'esito sul processo: {e2}")
@@ -171,6 +201,61 @@ def esegui(lavoro: dict, conf: dict, api: ApiNoeva, *, esporta_fn=esporta_pacche
         pulisci(conf["lavoro"] / progetto)
 
 
+def giro(argv: list[str], *, esporta_fn=esporta_pacchetto, pubblica_fn=pubblica.pubblica_versione,
+         biglietti_fn=pubblica.biglietto_dall_api) -> int:
+    """`noeva-snapshot giro --config worker.json --pipeline <nome>`: un giro solo, senza la coda.
+
+    E' il comando che lancia il worker NOEVA-ETL dove sullo stesso server girano
+    anche altre pipeline ETL (ADR 0004, punto 4): il processo lo prende lui, con il
+    suo claim, e chiama questo con il connettore `processo-esterno` (ADR-0096 di
+    noeva-etl). Il contratto e' quello del connettore: i log vanno su stderr, su
+    stdout solo l'esito come un unico documento JSON, e l'exit code dice se si e'
+    pubblicato. La chiave sta in NOEVA_API_KEY e la password del database nella
+    variabile di connessione.json, passate dal worker per nome."""
+    def opzione(nome: str) -> str:
+        if nome not in argv or argv.index(nome) + 1 >= len(argv):
+            raise SystemExit(f"giro: serve {nome}")
+        return argv[argv.index(nome) + 1]
+
+    conf = leggi_config(pathlib.Path(opzione("--config")))
+    pipeline = opzione("--pipeline")
+    if pipeline not in conf["pipeline"]:
+        raise SystemExit(f"giro: {pipeline} non e' in worker.json ({', '.join(sorted(conf['pipeline']))})")
+    chiave = os.environ.get("NOEVA_API_KEY")
+    if not chiave:
+        raise SystemExit("manca NOEVA_API_KEY: la chiave NOEVA dell'utente di servizio del worker")
+    p = conf["pipeline"][pipeline]
+    cartella = cartella_del_giro(conf, p["progetto"], "giro")
+
+    # Durante il giro stdout e' stderr, anche per il motore e i driver che scrivono
+    # direttamente sul descrittore 1: su stdout resta solo il JSON finale.
+    sys.stdout.flush()
+    stdout_vero = os.dup(1)
+    os.dup2(2, 1)
+    uscita = None
+    try:
+        with contextlib.redirect_stdout(sys.stderr):
+            log(f"{pipeline}: giro lanciato dal worker, in {cartella}")
+            try:
+                uscita, _ = genera_e_pubblica(p, conf, chiave, conf["workspace"], cartella,
+                                              esporta_fn=esporta_fn, pubblica_fn=pubblica_fn,
+                                              biglietti_fn=biglietti_fn)
+                uscita["cartella"] = str(cartella)
+                log(f"{pipeline}: pubblicata {uscita['versione']} in {uscita['secondi']}s")
+            except (Exception, SystemExit) as e:  # noqa: BLE001 - l'ultima riga di stderr e' il motivo
+                log(f"{pipeline}: FALLITO, {str(e).strip() or e.__class__.__name__}")
+            finally:
+                pulisci(conf["lavoro"] / p["progetto"])
+    finally:
+        sys.stderr.flush()
+        os.dup2(stdout_vero, 1)
+        os.close(stdout_vero)
+    if uscita is None:
+        return 1
+    print(json.dumps(uscita, default=str), flush=True)
+    return 0
+
+
 def pulisci(cartella_progetto: pathlib.Path) -> None:
     giri = sorted((d for d in cartella_progetto.iterdir() if d.is_dir()), key=lambda d: d.name)
     for vecchio in giri[:-GIRI_TENUTI]:

package/contenuto/lib/snapshot/noeva_snapshot.py

@@ -12,6 +12,7 @@ da `./aggiorna.sh snapshot`.
                             [--senza-controlli]
     noeva-snapshot pubblica <id> <dir dati> --url <contenitore>
     noeva-snapshot ascolta  --config <worker.json> [--una-volta] [--intervallo <s>]
+    noeva-snapshot giro     --config <worker.json> --pipeline <nome>   (lo lancia NOEVA-ETL: JSON su stdout)
     noeva-snapshot verifica --pacchetto <dir> --connessione <file.json>
     noeva-snapshot versione
 """
@@ -25,7 +26,7 @@ import ascolta
 import esporta
 import pubblica
 
-VERSIONE = "0.2.1"
+VERSIONE = "0.3.0"
 
 
 def _opzione(argv: list[str], nome: str) -> str | None:
@@ -97,10 +98,12 @@ def main(argv: list[str]) -> int:
         return verifica(resto)
     if comando == "ascolta":
         return ascolta.main(["ascolta", *resto])
+    if comando == "giro":
+        return ascolta.giro(resto)
     if comando == "versione":
         print(json.dumps({"runner": VERSIONE, "python": sys.version.split()[0]}))
         return 0
-    raise SystemExit(f"comando sconosciuto: {comando} (esporta, pubblica, ascolta, verifica, versione)")
+    raise SystemExit(f"comando sconosciuto: {comando} (esporta, pubblica, ascolta, giro, verifica, versione)")
 
 
 if __name__ == "__main__":

package/contenuto/lib/snapshot/worker/installa.ps1

@@ -3,6 +3,8 @@
 #
 #   powershell -ExecutionPolicy Bypass -File .\installa.ps1                  installa o aggiorna
 #   powershell -ExecutionPolicy Bypass -File .\installa.ps1 -SoloControllo   controlla e basta (dopo un riavvio)
+#   ... -ConNoevaEtl   dove sul server gira gia' il worker NOEVA-ETL (ADR 0004, punto 4): i giri
+#                      li prende lui e lancia `noeva-snapshot giro`; nessuna attivita' pianificata
 #
 # Si lancia dalla cartella estratta dallo zip, ENTRANDO IN WINDOWS COME L'UTENTE CHE FARA'
 # GIRARE IL WORKER: le chiavi vanno nelle sue variabili d'ambiente. La copia in
@@ -12,7 +14,7 @@
 # pianificata prende il posto (ogni {{minuti}} minuti, ascolta --una-volta).
 # Nessun segreto finisce a schermo o nel file dell'esito.
 
-param([switch]$SoloControllo)
+param([switch]$SoloControllo, [switch]$ConNoevaEtl)
 
 $ErrorActionPreference = 'Stop'
 try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch { }
@@ -266,12 +268,24 @@ else {
 }
 
 # 6. Il primo giro ------------------------------------------------------------------------------
-if ($SoloControllo) {
+if ($SoloControllo -and $ConNoevaEtl) {
+    Esito 'ultimo giro' 'saltato' "i giri li lancia NOEVA-ETL: l'esito sta nei Processi del workspace ($pipeline)"
+} elseif ($SoloControllo) {
     $log = Join-Path $destinazione 'lavoro\ascolta.log'
     if (Test-Path $log) {
         $ultima = Get-Content $log -Tail 40 | Where-Object { $_ -match 'pubblicata|FALLITO' } | Select-Object -Last 1
         Esito 'ultimo giro' $(if ($ultima -match 'FALLITO') { 'NO' } elseif ($ultima) { 'ok' } else { 'avviso' }) $(if ($ultima) { $ultima.Trim() } else { 'nessun giro ancora in ascolta.log' })
     } else { Esito 'ultimo giro' 'avviso' 'ascolta.log non c''e'' ancora' }
+} elseif ($ConNoevaEtl) {
+    Passo '6. Il primo giro, adesso'
+    Write-Host '  Lo stesso comando che lancera'' NOEVA-ETL, qui davanti e senza passare dalla coda.'
+    if (Chiedi 'Faccio partire adesso il primo giro (circa 10 minuti)?') {
+        $g = EseguiDalVivo $exe @('giro', '--config', (Join-Path $destinazione 'worker.json'), '--pipeline', $pipeline)
+        $pubblicata = [regex]::Match($g.Testo, ': pubblicata (\S+) in')
+        $fallito = @($g.Testo -split "`n" | Where-Object { $_ -match 'FALLITO' }) | Select-Object -First 1
+        if ($g.Codice -eq 0 -and $pubblicata.Success) { Esito 'primo giro' 'ok' "pubblicata la versione $($pubblicata.Groups[1].Value)" }
+        else { Esito 'primo giro' 'NO' $(if ($fallito) { $fallito.Trim() } else { "uscita $($g.Codice)" }) }
+    } else { Esito 'primo giro' 'saltato' 'lo fara'' NOEVA-ETL alla prossima schedulazione' }
 } else {
     Passo '6. Il primo giro, adesso'
     if (Chiedi 'Faccio partire adesso il primo giro (circa 4 minuti)?') {
@@ -299,7 +313,16 @@ if ($SoloControllo) {
 
 # 7. L'attivita' pianificata --------------------------------------------------------------------
 Passo "7. L'attivita' pianificata '$attivita'"
-if ($SoloControllo) {
+if ($ConNoevaEtl) {
+    # Con NOEVA-ETL sul server un secondo worker in ascolto si contenderebbe i processi
+    # con lui: l'attivita' non deve esserci, e se c'e' da un'installazione di prima si toglie.
+    $t = Get-ScheduledTask -TaskName $attivita -ErrorAction SilentlyContinue
+    if ($t -and $SoloControllo) { Esito 'attivita''' 'NO' 'c''e'' ancora: con NOEVA-ETL va tolta (rilancia senza -SoloControllo)' }
+    elseif ($t) {
+        Unregister-ScheduledTask -TaskName $attivita -Confirm:$false
+        Esito 'attivita''' 'ok' "tolta: i giri di $pipeline li lancia NOEVA-ETL"
+    } else { Esito 'attivita''' 'ok' "nessuna: i giri di $pipeline li lancia NOEVA-ETL" }
+} elseif ($SoloControllo) {
     $t = Get-ScheduledTask -TaskName $attivita -ErrorAction SilentlyContinue
     if (-not $t) { Esito 'attivita''' 'NO' 'non installata: rilancia senza -SoloControllo' }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noeva/analytics-core",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Gli strumenti di un progetto NOEVA Analytics nel suo repository: moduli di pagina, snapshot, verifica dello standard e kit dell'agente (ADR 0005).",
   "type": "module",
   "bin": {