@noeva/analytics-core 0.1.0 → 0.3.0

package/contenuto/lib/snapshot/ascolta.py

@@ -0,0 +1,213 @@
+"""noeva-snapshot ascolta: prende dalla coda di NOEVA i giri di snapshot del suo workspace e li esegue.
+
+La cadenza la decide il workspace dal pannello NOEVA (Schedulazioni, azione `etl`,
+funzione `analytics-snapshot-<progetto>`): lo scheduler crea un processo in coda, e
+questo comando, sul server del cliente, lo prende (POST /api/processes/etl/claim,
+solo le pipeline che conosce), genera lo snapshot dal database, chiede il biglietto
+all'API (POST /api/analytics/biglietto-dati), lo pubblica nel contenitore e scrive
+l'esito sul processo (PATCH /api/processes/etl/<id>/progress). Gli stessi endpoint
+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)
+
+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):
+
+    {"api": "https://api.noeva.ai", "contenitore": "https://analytics.noeva.ai",
+     "workspace": "<id del workspace>", "lavoro": "lavoro",
+     "pipeline": {"analytics-snapshot-<id>": {"progetto": "<id>",
+                  "pacchetto": "pacchetti/<id>", "connessione": "pacchetti/<id>/connessione.json"}}}
+
+Solo libreria standard, come pubblica.py: il motore (esporta.py) si importa solo
+quando c'e' un giro da fare.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import pathlib
+import shutil
+import socket
+import sys
+import time
+import urllib.error
+import urllib.request
+
+import pubblica
+
+# Il report del giro (l'SQL eseguito, ADR 0004) va nell'esito del processo se ci
+# sta; quello del progetto piu' grande pesa 460 KB. Oltre, solo il riassunto.
+MAX_REPORT_BYTE = 512 * 1024
+# I giri tenuti nella cartella di lavoro, per progetto: per rivedere un giro fallito.
+GIRI_TENUTI = 5
+
+
+def adesso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def log(testo: str) -> None:
+    print(f"{dt.datetime.now().strftime('%Y-%m-%d %H:%M:%S')} {testo}", flush=True)
+
+
+class ApiNoeva:
+    """Le due chiamate del worker all'API NOEVA, con la chiave e il workspace."""
+
+    def __init__(self, base: str, chiave: str, workspace: str, worker_id: str):
+        self.base, self.chiave, self.workspace, self.worker_id = base.rstrip("/"), chiave, workspace, worker_id
+
+    def _chiama(self, metodo: str, percorso: str, corpo: dict) -> tuple[int, dict | None]:
+        r = urllib.request.Request(
+            f"{self.base}{percorso}", data=json.dumps(corpo, default=str).encode(), method=metodo,
+            headers={"Authorization": f"Bearer {self.chiave}", "x-noeva-workspace": self.workspace,
+                     "Content-Type": "application/json", "User-Agent": pubblica.AGENTE})
+        try:
+            with urllib.request.urlopen(r, timeout=60) as risposta:
+                testo = risposta.read()
+                return risposta.status, (json.loads(testo) if testo else None)
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"{metodo} {percorso}: HTTP {e.code} {e.read().decode(errors='replace')[:300]}") from e
+
+    def prendi(self, pipelines: list[str]) -> dict | None:
+        """Il prossimo processo in coda di una di queste pipeline, o None."""
+        stato, corpo = self._chiama("POST", "/api/processes/etl/claim",
+                                    {"workerId": self.worker_id, "pipelines": pipelines})
+        return None if stato == 204 or not corpo else corpo["payload"]
+
+    def avanza(self, processo: str, **campi) -> None:
+        self._chiama("PATCH", f"/api/processes/etl/{processo}/progress", campi)
+
+
+def leggi_config(percorso: pathlib.Path) -> dict:
+    conf = json.loads(percorso.read_text(encoding="utf-8"))
+    radice = percorso.resolve().parent
+    for chiave in ("api", "contenitore", "workspace", "pipeline"):
+        if not conf.get(chiave):
+            raise SystemExit(f"{percorso}: manca {chiave}")
+    conf["lavoro"] = (radice / conf.get("lavoro", "lavoro")).resolve()
+    for nome, p in conf["pipeline"].items():
+        for chiave in ("progetto", "pacchetto", "connessione"):
+            if not p.get(chiave):
+                raise SystemExit(f"{percorso}: la pipeline {nome} non ha {chiave}")
+        p["pacchetto"] = (radice / p["pacchetto"]).resolve()
+        p["connessione"] = (radice / p["connessione"]).resolve()
+    return conf
+
+
+def esporta_pacchetto(pacchetto: pathlib.Path, connessione: pathlib.Path, uscita: pathlib.Path,
+                      report: pathlib.Path) -> None:
+    """Lo snapshot come `noeva-snapshot esporta`: solleva SystemExit se una cifra di
+    controllo non torna (allora non si pubblica niente)."""
+    import esporta  # il motore: pesante, solo quando serve
+
+    codice = esporta.main(["esporta", str(pacchetto), "--mdl", str(pacchetto / "mdl.json"),
+                           "--connessione", str(connessione), "--uscita", str(uscita), "--report", str(report)])
+    if codice:
+        raise SystemExit(f"esporta e' uscito con {codice}")
+
+
+def riassunto(report: dict | None) -> dict:
+    if not report:
+        return {}
+    esiti: dict[str, int] = {}
+    for c in report.get("controlli", []):
+        esiti[c.get("esito", "?")] = esiti.get(c.get("esito", "?"), 0) + 1
+    return {
+        "controlli": esiti,
+        "avvisi": [c["nome"] for c in report.get("controlli", []) if c.get("esito") == "avviso"],
+        "estrazioni": len(report.get("estrazioni", [])),
+    }
+
+
+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."""
+    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)
+    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),
+        }
+        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")
+        return True
+    except (Exception, SystemExit) as e:  # noqa: BLE001 - qualunque errore chiude il processo come fallito
+        messaggio = str(e).strip() or e.__class__.__name__
+        log(f"{pipeline}: FALLITO, {messaggio}")
+        try:
+            api.avanza(processo, status="failed", errorMessage=messaggio[:2000],
+                       outputData={"progetto": progetto, "secondi": round(time.time() - inizio, 1),
+                                   **riassunto(report)},
+                       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}")
+        return False
+    finally:
+        pulisci(conf["lavoro"] / progetto)
+
+
+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]:
+        shutil.rmtree(vecchio, ignore_errors=True)
+
+
+def main(argv: list[str]) -> int:
+    if "--config" not in argv or argv.index("--config") + 1 >= len(argv):
+        raise SystemExit("ascolta: serve --config <worker.json>")
+    conf = leggi_config(pathlib.Path(argv[argv.index("--config") + 1]))
+    una_volta = "--una-volta" in argv
+    intervallo = int(argv[argv.index("--intervallo") + 1]) if "--intervallo" in argv else 60
+    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")
+    api = ApiNoeva(conf["api"], chiave, conf["workspace"], f"noeva-snapshot@{socket.gethostname()}")
+    pipelines = sorted(conf["pipeline"])
+    log(f"in ascolto per {', '.join(pipelines)} su {conf['api']}"
+        + (" (una volta)" if una_volta else f", ogni {intervallo}s"))
+
+    falliti = 0
+    while True:
+        try:
+            lavoro = api.prendi(pipelines)
+        except Exception as e:  # noqa: BLE001 - rete o API giu': si riprova al prossimo giro
+            log(f"non riesco a chiedere lavoro all'API: {e}")
+            if una_volta:
+                return 1
+            time.sleep(intervallo)
+            continue
+        if lavoro:
+            falliti += not esegui(lavoro, conf, api)
+            continue  # subito il prossimo: in coda ce ne puo' essere un altro
+        if una_volta:
+            return 1 if falliti else 0
+        time.sleep(intervallo)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/contenuto/lib/snapshot/impacchetta.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python
+"""L'eseguibile degli snapshot e il pacchetto di un progetto, per il worker dal cliente (ADR 0004).
+
+Due cose separate, con ritmi diversi:
+
+  eseguibile   noeva-snapshot[.exe]: motore Wren, driver, esporta.py e pubblica.py.
+               UNO per tutti i progetti, cambia solo con la versione del motore.
+               Stessa ricetta PyInstaller e stesso ambiente (lib/mcp-locale/ambiente)
+               dell'eseguibile MCP dei PC: le versioni provate sono quelle.
+  pacchetto    <id>/: snapshot.yml e mdl.json con i nomi dei database del cliente
+               (la stessa trasformazione del pacchetto MCP: lib/mcp-locale/<id>.yml),
+               piu' connessione.json senza password. Pochi KB: a regime lo
+               scarica il worker dall'API a ogni giro.
+  worker       accanto al pacchetto: worker.json (la pipeline del progetto, il
+               suo workspace, l'API e il contenitore) e installa.ps1 di
+               lib/snapshot/worker/: installa o aggiorna passo per passo (rete,
+               driver, chiavi, verifica, primo giro, attivita' pianificata che
+               lancia `noeva-snapshot ascolta --una-volta`) e chiude con l'esito.
+               Escono con `pacchetto`.
+
+    uv run --with pyyaml python lib/snapshot/impacchetta.py eseguibile
+    uv run --with pyyaml python lib/snapshot/impacchetta.py pacchetto project-<id>
+
+oppure dal repository di un progetto (ADR 0005), con la configurazione in
+consegna.yml e il workspace in analytics.json, uscita in dist/snapshot/ del
+repository:
+
+    uv run --with pyyaml python $(npx analytics percorso)/lib/snapshot/impacchetta.py eseguibile .
+    uv run --with pyyaml python $(npx analytics percorso)/lib/snapshot/impacchetta.py pacchetto .
+
+Escono in dist/snapshot/. Come per l'eseguibile MCP, quello per Windows si
+costruisce su Windows; sul Mac pyodbc resta fuori (vuole unixODBC) e l'eseguibile
+serve a provare la ricetta, non a leggere un SQL Server.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import shutil
+import sys
+
+import yaml
+
+RADICE = pathlib.Path(__file__).resolve().parents[2]
+QUI = pathlib.Path(__file__).resolve().parent
+# lib/mcp-locale sta accanto a lib/snapshot nel monorepo e nel pacchetto (contenuto/lib/).
+sys.path.insert(0, str(QUI.parent / "mcp-locale"))
+import costruisci  # noqa: E402 - la ricetta e l'ambiente dell'eseguibile MCP
+
+USCITA = RADICE / "dist" / "snapshot"
+NOME = "noeva-snapshot"
+API = "https://api.noeva.ai"
+CONTENITORE = "https://analytics.noeva.ai"
+# Ogni quanti minuti l'attivita' pianificata chiede a NOEVA se c'e' un giro in coda.
+MINUTI = 5
+
+
+def argomenti(build: pathlib.Path) -> list:
+    return [
+        "--noconfirm", "--clean", "--onedir", "--console",
+        "--name", NOME,
+        "--distpath", build / "dist", "--workpath", build / "work", "--specpath", build,
+        # esporta.py e pubblica.py stanno accanto all'ingresso
+        "--paths", QUI,
+        "--collect-submodules", "wren", "--collect-data", "wren",
+        "--collect-submodules", "sqlglot",
+        *(["--exclude-module", "pyodbc"] if sys.platform == "darwin" else ["--hidden-import", "pyodbc"]),
+        "--copy-metadata", "wrenai",
+        # niente server MCP, memoria o interfacce: solo il motore e il runner
+        "--exclude-module", "lancedb", "--exclude-module", "onnxruntime",
+        "--exclude-module", "tkinter", "--exclude-module", "IPython",
+        "--exclude-module", "pkg_resources", "--exclude-module", "setuptools",
+        QUI / "noeva_snapshot.py",
+    ]
+
+
+def eseguibile() -> pathlib.Path:
+    amb = costruisci.ambiente()
+    build = USCITA / "_pyinstaller"
+    if build.exists():
+        shutil.rmtree(build)
+    costruisci.uv_run(amb, "pyinstaller", *argomenti(build))
+    dest = USCITA / NOME
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(build / "dist" / NOME, dest)
+    peso = sum(f.stat().st_size for f in dest.rglob("*") if f.is_file()) // 1024 // 1024
+    print(f"eseguibile: {costruisci.relativo(dest)} ({peso} MB)")
+    return dest
+
+
+def pacchetto(progetto: str) -> pathlib.Path:
+    sorgente, ident, conf, _ = costruisci.progetto(progetto)
+    vive = conf.get("sorgenti") or {}
+    if len(vive) != 1:
+        raise SystemExit(f"{ident}: il pacchetto vuole una sorgente sola (un progetto, una sorgente), "
+                         f"trovate {len(vive)}")
+    (chiave, s), = vive.items()
+
+    dest = USCITA / "pacchetti" / ident
+    if dest.exists():
+        shutil.rmtree(dest)
+    lavoro = USCITA / "_modelli" / ident
+    if lavoro.exists():
+        shutil.rmtree(lavoro)
+    lavoro.parent.mkdir(parents=True, exist_ok=True)
+    # Il modello con i nomi di produzione, come per il pacchetto MCP dei PC.
+    conta = costruisci.modello_vivo(sorgente, lavoro, s)
+    costruisci.uv_run(costruisci.ambiente(), "wren", "context", "build", "--path", lavoro)
+    dest.mkdir(parents=True)
+    shutil.copy2(lavoro / "target" / "mdl.json", dest / "mdl.json")
+    shutil.copy2(sorgente / "snapshot.yml", dest / "snapshot.yml")
+    # La sorgente senza password: la password la digita chi installa, nella
+    # variabile d'ambiente che password_env nomina.
+    connessione = {"tipo": "mssql", **{c: s[c] for c in ("host", "porta", "database", "utente", "password_env",
+                                                         "driver", "opzioni") if c in s}}
+    (dest / "connessione.json").write_text(json.dumps(connessione, indent=1) + "\n", encoding="utf-8")
+    print(f"pacchetto: {costruisci.relativo(dest)} · {conta['rinominati']} riferimenti rinominati, "
+          f"{conta['catalogo']} modelli col catalogo {s.get('catalogo_senza_nome') or '-'} · sorgente {chiave}")
+    worker(ident, connessione, sorgente)
+    return dest
+
+
+def workspace_di(ident: str, sorgente: pathlib.Path) -> str:
+    """Il workspace che possiede il progetto: analytics.json del repository, o il registro del monorepo."""
+    f = sorgente / "analytics.json"
+    if f.is_file():
+        workspace = json.loads(f.read_text(encoding="utf-8")).get("workspace")
+    else:
+        registro = json.loads((RADICE / "lib" / "rilascio" / "progetti.json").read_text(encoding="utf-8"))
+        workspace = ((registro["progetti"].get(ident) or {}).get("analytics") or {}).get("workspace")
+    if not workspace:
+        raise SystemExit(f"{ident}: manca il workspace (analytics.json del repository, o analytics.workspace nel registro)")
+    return workspace
+
+
+def worker(ident: str, connessione: dict, sorgente: pathlib.Path) -> None:
+    """worker.json e gli script di Windows per `noeva-snapshot ascolta` (ADR 0004)."""
+    workspace = workspace_di(ident, sorgente)
+    conf = {
+        "api": API, "contenitore": CONTENITORE, "workspace": workspace, "lavoro": "lavoro",
+        "pipeline": {f"analytics-snapshot-{ident}": {
+            "progetto": ident, "pacchetto": f"pacchetti/{ident}",
+            "connessione": f"pacchetti/{ident}/connessione.json"}},
+    }
+    (USCITA / "worker.json").write_text(json.dumps(conf, indent=1) + "\n", encoding="utf-8")
+    valori = {"progetto": ident, "utente": connessione["utente"], "password_env": connessione["password_env"],
+              "host": connessione["host"], "porta": str(connessione.get("porta") or 1433), "minuti": str(MINUTI)}
+    for script in sorted((QUI / "worker").glob("*.ps1")):
+        testo = script.read_text(encoding="utf-8")
+        for k, v in valori.items():
+            testo = testo.replace("{{" + k + "}}", v)
+        if "{{" in testo:
+            raise SystemExit(f"{script.name}: segnaposto senza valore")
+        # PowerShell 5 legge come ANSI un .ps1 UTF-8 senza BOM: con il BOM gli accenti restano.
+        (USCITA / script.name).write_text(testo, encoding="utf-8-sig")
+    print(f"worker: worker.json (pipeline analytics-snapshot-{ident}, workspace {workspace}) e "
+          f"{len(list((QUI / 'worker').glob('*.ps1')))} script")
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cosa", required=True)
+    e = sub.add_parser("eseguibile")
+    e.add_argument("progetto", nargs="?", help="il repository del progetto: l'uscita va nella sua dist/")
+    p = sub.add_parser("pacchetto")
+    p.add_argument("progetto", help="project-<id> del monorepo, o il repository del progetto (con analytics.json)")
+    a = ap.parse_args(argv[1:])
+    global USCITA
+    if a.progetto:
+        _, _, _, uscita_mcp = costruisci.progetto(a.progetto)
+        USCITA = uscita_mcp.parent / "snapshot"
+        costruisci.USCITA = uscita_mcp  # relativo() stampa rispetto al repository
+    USCITA.mkdir(parents=True, exist_ok=True)
+    if a.cosa == "eseguibile":
+        eseguibile()
+    else:
+        pacchetto(a.progetto)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/contenuto/lib/snapshot/noeva_snapshot.py

@@ -0,0 +1,107 @@
+"""Il runner degli snapshot che gira dal cliente (ADR 0004), senza Docker e senza Python.
+
+Si consegna come eseguibile (PyInstaller, `noeva-snapshot[.exe]`, costruito da
+lib/snapshot/impacchetta.py). I giri li lancia lo scheduler di NOEVA: `ascolta`
+li prende dalla coda del workspace (ascolta.py). E' UNO per tutti i
+progetti: il modello non sta dentro, arriva con il pacchetto del progetto
+(snapshot.yml + mdl.json) a ogni giro. Dentro ci sono il motore Wren, i driver e
+gli stessi esporta.py e pubblica.py del repository: lo snapshot si genera come
+da `./aggiorna.sh snapshot`.
+
+    noeva-snapshot esporta  --pacchetto <dir> --connessione <file.json> --uscita <dir> --report <file.json>
+                            [--senza-controlli]
+    noeva-snapshot pubblica <id> <dir dati> --url <contenitore>
+    noeva-snapshot ascolta  --config <worker.json> [--una-volta] [--intervallo <s>]
+    noeva-snapshot verifica --pacchetto <dir> --connessione <file.json>
+    noeva-snapshot versione
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+
+import ascolta
+import esporta
+import pubblica
+
+VERSIONE = "0.2.1"
+
+
+def _opzione(argv: list[str], nome: str) -> str | None:
+    if nome in argv:
+        i = argv.index(nome)
+        if i + 1 < len(argv):
+            return argv[i + 1]
+    return None
+
+
+def esporta_(argv: list[str]) -> int:
+    pacchetto = _opzione(argv, "--pacchetto")
+    if not pacchetto:
+        raise SystemExit("esporta: serve --pacchetto <cartella con snapshot.yml e mdl.json>")
+    p = pathlib.Path(pacchetto).resolve()
+    resto = [a for i, a in enumerate(argv) if a != "--pacchetto" and (i == 0 or argv[i - 1] != "--pacchetto")]
+    return esporta.main(["esporta", str(p), "--mdl", str(p / "mdl.json"), *resto])
+
+
+def verifica(argv: list[str]) -> int:
+    """Connessione e cifre di controllo, senza scrivere niente: quello che si
+    lancia a mano da chi installa, prima di lasciare il server."""
+    pacchetto = pathlib.Path(_opzione(argv, "--pacchetto") or ".").resolve()
+    connessione = _opzione(argv, "--connessione")
+    if not connessione:
+        raise SystemExit("verifica: serve --connessione <file.json>")
+    import yaml
+
+    conf = yaml.safe_load((pacchetto / "snapshot.yml").read_text(encoding="utf-8")) or {}
+    eng, nome, _ = esporta.motore(pacchetto, mdl=pacchetto / "mdl.json", connessione=pathlib.Path(connessione))
+    print(f"noeva-snapshot {VERSIONE} · {pacchetto.name} · {nome}")
+    falliti = 0
+    try:
+        for c in conf.get("controlli") or []:
+            try:
+                r = eng.query(c["sql"]).to_pylist()
+                trovato = float(next(iter(r[0].values())) or 0) if r else 0.0
+                esito = esporta.valuta(c, trovato)
+                print(f"  {'NO' if esito == 'diverso' else esito}  {c['nome']}: {trovato:,.2f} "
+                      f"(atteso {float(c['atteso']):,.2f})")
+                falliti += esito == "diverso"
+            except Exception as e:  # noqa: BLE001 - si mostra l'errore, qualunque sia
+                # Il primo errore basta: quasi sempre e' la connessione (rete, driver,
+                # password), e ripeterlo per ogni controllo vorrebbe dire un timeout ciascuno.
+                print(f"  NO  {c['nome']}: {str(e).strip().splitlines()[0][:300]}")
+                falliti += 1
+                print("  mi fermo al primo errore: sistemato quello, si rilancia")
+                break
+    finally:
+        eng.close()
+    print("tutto a posto" if not falliti else f"{falliti} controlli non tornano (gli avvisi non fermano)")
+    return 1 if falliti else 0
+
+
+def main(argv: list[str]) -> int:
+    # Su Windows, in una pipe o in un file, la console non e' UTF-8: chi installa
+    # legge «·» e gli accenti come «�». UTF-8 sempre, e mai un'eccezione per un carattere.
+    for flusso in (sys.stdout, sys.stderr):
+        flusso.reconfigure(encoding="utf-8", errors="replace")
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    comando, resto = argv[1], argv[2:]
+    if comando == "esporta":
+        return esporta_(resto)
+    if comando == "pubblica":
+        return pubblica.main(["pubblica", *resto])
+    if comando == "verifica":
+        return verifica(resto)
+    if comando == "ascolta":
+        return ascolta.main(["ascolta", *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)")
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/contenuto/lib/snapshot/pubblica.py

@@ -46,22 +46,37 @@ def _b64(byte: bytes) -> str:
     return base64.urlsafe_b64encode(byte).decode().rstrip("=")
 
 
-def biglietto(segreto: str, progetto: str, versione: str, ws: str, da: str, durata_s: int = 900) -> str:
+def biglietto(segreto: str, progetto: str, versione: str, ws: str, da: str, durata_s: int = 900,
+              tipo: str = "dati") -> str:
     """Lo stesso formato di lib/cancello/sessione.js: base64url(JSON).base64url(HMAC-SHA256).
 
     `ws` e' il workspace che possiede il progetto: il contenitore rifiuta un biglietto
-    con un altro workspace (lo stesso controllo vale per quelli dell'API NOEVA)."""
-    payload = {"tipo": "dati", "prog": progetto, "ver": versione, "ws": ws, "da": da,
+    con un altro workspace (lo stesso controllo vale per quelli dell'API NOEVA).
+    `tipo` dice cosa apre: "dati" lo snapshot, "modello" il modello compilato
+    (lib/modello/pubblica.py)."""
+    payload = {"tipo": tipo, "prog": progetto, "ver": versione, "ws": ws, "da": da,
                "exp": int((time.time() + durata_s) * 1000)}
     corpo = _b64(json.dumps(payload, separators=(",", ":")).encode())
     mac = hmac.new(segreto.encode(), corpo.encode(), hashlib.sha256).digest()
     return f"{corpo}.{_b64(mac)}"
 
 
-def workspace_dal_registro(progetto: str) -> str:
+def workspace_dal_registro(progetto: str, vicino: pathlib.Path | None = None) -> str:
+    """Il workspace che possiede il progetto: da analytics.json del repository del
+    progetto (risalendo da `vicino`, la cartella dei dati), o dal registro del monorepo.
+
+    Fuori dal monorepo il registro non c'e' (ADR 0005): il repository del progetto
+    scrive il suo workspace in analytics.json."""
+    for d in ([vicino.resolve(), *vicino.resolve().parents] if vicino else []):
+        f = d / "analytics.json"
+        if f.is_file():
+            c = json.loads(f.read_text(encoding="utf-8"))
+            if c.get("progetto") == progetto and c.get("workspace"):
+                return c["workspace"]
+            break
     registro = pathlib.Path(__file__).resolve().parents[1] / "rilascio" / "progetti.json"
     if not registro.is_file():
-        raise SystemExit("serve --workspace: il registro dei progetti non c'e'")
+        raise SystemExit("serve --workspace (o `workspace` in analytics.json): il registro dei progetti non c'e'")
     voce = json.loads(registro.read_text(encoding="utf-8"))["progetti"].get(progetto) or {}
     ws = (voce.get("analytics") or {}).get("workspace")
     if not ws:
@@ -75,11 +90,13 @@ API_NOEVA = "https://api.noeva.ai"
 AGENTE = "noeva-snapshot (NOEVA Analytics)"
 
 
-def biglietto_dall_api(api: str, chiave: str, workspace: str, progetto: str, versione: str, da: str) -> str:
+def biglietto_dall_api(api: str, chiave: str, workspace: str, progetto: str, versione: str, da: str,
+                       tipo: str = "dati") -> str:
     """Il biglietto rilasciato dall'API NOEVA a un membro del workspace (noeva-server-api,
     POST /api/analytics/biglietto-dati). Il contenitore lo accetta solo se il workspace
-    possiede il progetto."""
-    corpo = json.dumps({"progetto": progetto, "versione": versione, "da": da}).encode()
+    possiede il progetto. `tipo` "dati" non si manda: l'API di prima non lo conosce."""
+    richiesta = {"progetto": progetto, "versione": versione, "da": da, **({"tipo": tipo} if tipo != "dati" else {})}
+    corpo = json.dumps(richiesta).encode()
     risposta = chiama("POST", f"{api.rstrip('/')}/api/analytics/biglietto-dati", chiave, corpo,
                       intestazioni={"x-noeva-workspace": workspace, "Content-Type": "application/json"})
     return risposta["payload"]["biglietto"]
@@ -96,7 +113,8 @@ def dal_file(variabile: str, nome: str) -> str | None:
     return f.read_text(encoding="utf-8").strip() or None if f.is_file() else None
 
 
-def sorgente_biglietti(progetto: str, da: str, *, api: str | None = None, workspace: str | None = None):
+def sorgente_biglietti(progetto: str, da: str, *, api: str | None = None, workspace: str | None = None,
+                       tipo: str = "dati", vicino: pathlib.Path | None = None):
     """Una funzione versione -> biglietto. Due strade:
 
     - firmato qui col segreto del contenitore (SEGRETO_DATI o ~/.segreto-dati): il Mac
@@ -105,18 +123,19 @@ def sorgente_biglietti(progetto: str, da: str, *, api: str | None = None, worksp
       sia membro del workspace che possiede il progetto, col modulo Analytics. E' la
       strada di chi rilascia i dati senza avere il segreto, e del worker dal cliente.
 
-    Il workspace e' --workspace, NOEVA_WORKSPACE o quello del registro."""
+    Il workspace e' --workspace, NOEVA_WORKSPACE, quello di analytics.json del repository
+    del progetto o quello del registro. `tipo` dice cosa apre il biglietto: dati, pagine, modello."""
     segreto = dal_file("SEGRETO_DATI", ".segreto-dati")
     if segreto:
-        ws = workspace or workspace_dal_registro(progetto)
-        return lambda versione: biglietto(segreto, progetto, versione, ws, da)
+        ws = workspace or workspace_dal_registro(progetto, vicino)
+        return lambda versione: biglietto(segreto, progetto, versione, ws, da, tipo=tipo)
     chiave = dal_file("NOEVA_API_KEY", ".noeva-api-key")
     if not chiave:
         raise SystemExit("serve il segreto del contenitore (~/.segreto-dati) o la tua chiave API NOEVA "
                          "(~/.noeva-api-key): vedi docs/pubblicare-le-dashboard.md")
-    ws = workspace or os.environ.get("NOEVA_WORKSPACE") or workspace_dal_registro(progetto)
+    ws = workspace or os.environ.get("NOEVA_WORKSPACE") or workspace_dal_registro(progetto, vicino)
     base_api = api or os.environ.get("NOEVA_API", API_NOEVA)
-    return lambda versione: biglietto_dall_api(base_api, chiave, ws, progetto, versione, da)
+    return lambda versione: biglietto_dall_api(base_api, chiave, ws, progetto, versione, da, tipo=tipo)
 
 
 def versione_di(cartella: pathlib.Path) -> str:
@@ -192,7 +211,8 @@ def main(argv: list[str]) -> int:
     ap.add_argument("--api", help=f"l'API NOEVA che rilascia il biglietto (default: NOEVA_API o {API_NOEVA})")
     a = ap.parse_args(argv[1:])
 
-    biglietto_per = sorgente_biglietti(a.progetto, a.da, api=a.api, workspace=a.workspace)
+    biglietto_per = sorgente_biglietti(a.progetto, a.da, api=a.api, workspace=a.workspace,
+                                       vicino=pathlib.Path(a.dati) if a.dati else None)
     base = a.url.rstrip("/")
 
     if a.rollback: