release: v1.0.0

Roadmap completa verso la produzione: py.typed + mypy --strict, CI
GitHub Actions, metadata PyPI (Repository/Issues), installazione da
PyPI documentata, --timeout configurabile, coverage 89%→99% (+ fix di
un bug reale: --format invalido produceva un traceback), CHANGELOG.md,
knowledge bundle OKF in knowledge/, valutazione produzione in docs/.

Nessun push, tag o pubblicazione PyPI in questo commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: aborruso

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type-check (mypy)
+        run: uv run mypy src/openrndt
+
+      - name: Test (pytest)
+        run: uv run pytest -v

.gitignore

@@ -24,3 +24,6 @@ tmp.md
 # Local outputs
 *.out
 out.txt
+
+# Test coverage
+.coverage

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Tutte le modifiche rilevanti di questo progetto sono documentate qui.
+
+Il formato segue [Keep a Changelog](https://keepachangelog.com/it/1.0.0/); il progetto segue [Semantic Versioning](https://semver.org/lang/it/).
+
+## [1.0.0] - 2026-07-17
+
+### Added
+
+- Type-checking `mypy --strict` in CI e come dipendenza dev.
+- `py.typed` (PEP 561): la libreria distribuisce i tipi a chi la importa.
+- CI GitHub Actions (`.github/workflows/ci.yml`): ruff, mypy, pytest su push/PR, matrice Python 3.12/3.13.
+- Opzione globale `--timeout` per il timeout HTTP per singolo tentativo (default 30s).
+- Metadata PyPI: `Repository`/`Issues` in `[project.urls]`.
+- Sezione README per l'installazione da PyPI (`uv tool install openrndt` / `uvx`).
+- Suite di test estesa a 55 test, coverage 99%.
+
+### Fixed
+
+- `--format <valore-invalido>` produceva un traceback completo invece di un messaggio leggibile: ora catturato ed esce con codice 2, coerente col principio "mai uno stack trace".
+
+## [0.1.0] - 2026-05-27
+
+### Added
+
+- Comandi `search`, `get`, `discover` (MVP read-only sul RNDT).
+- Libreria Python parallela alla CLI (`search`, `get_item`, `get_item_xml`, `get_item_html`, `ItemNotFoundError`).
+- Formati di output `json` (default), `table`, `csv`, `compact` (NDJSON per agenti AI).
+- Gestione errori pensata per orchestrazione LLM: mai stack trace, exit code distinti (0/1/2), messaggi self-contained su stderr.
+- Retry esponenziale su timeout/5xx (`tenacity`).
+- Codelist offline (ISO 19115, campi Lucene, formati) per `discover`, senza chiamate di rete.
+- Skill Claude Code `rndt-explorer` per l'esplorazione guidata del catalogo.
+- Bug noti dell'API RNDT documentati e compensati (`dataCategory` che non filtra, `sort` "amichevole" ignorato, item inesistente → 200 con `found: false`).

LOG.md

@@ -1,5 +1,18 @@
 # LOG
 
+## 2026-07-17
+
+- **Valutazione readiness produzione v0.1.0** in `docs/evaluation-v0.1.0.md`: codice production-grade, gap tutti infrastrutturali (no CI, no mypy, metadata PyPI incompleti, manca `py.typed` e CHANGELOG). Roadmap verso v1.0 inclusa.
+- **Knowledge bundle OKF** in `knowledge/`: documentazione del progetto in Open Knowledge Format (markdown + frontmatter YAML, leggibile da umani e agenti). 18 file: project, architecture, skill, cli/ (search, get, discover), library/, api/ (endpoint + bug noti verificati live), conventions/ (errori, output, testing). Validato conforme OKF v0.1 (frontmatter `type`, cross-link integri).
+- **`py.typed`** (PEP 561) aggiunto in `src/openrndt/`: verificato presente nel wheel dopo `uv build` senza bisogno di config aggiuntiva (`uv_build` lo include automaticamente). 38/38 test verdi. Primo punto della roadmap v1.0 in `docs/evaluation-v0.1.0.md`.
+- **`mypy --strict` pulito** (secondo punto roadmap): aggiunto al gruppo dev, config `[tool.mypy]` in `pyproject.toml`. 5 fix reali: `discover()` in `cli.py` riusava la variabile `section` con due tipi diversi (rinominata `values`); `dict` senza type-arg in `client.py`; 3 `no-any-return` (`response.json()` non annotato) in `search.py`/`item.py`, risolti annotando la variabile o con `cast`. 38/38 test e ruff ancora verdi.
+- **CI GitHub Actions** (terzo punto roadmap): `.github/workflows/ci.yml`, matrice Python 3.12/3.13, step `uv sync --locked` → `ruff check` → `mypy` → `pytest -v` su push/PR verso main. Sequenza verificata localmente prima del commit.
+- **Metadata `[project.urls]`** (quarto punto): aggiunti `Repository`/`Issues` verso `github.com/ondata/openrndt`; rinominati i link RNDT (`RNDT Portal`/`RNDT REST API`) per chiarire che non sono il repo del codice.
+- **README: installazione da PyPI** (quinto punto): sezione dedicata con `uv tool install openrndt`/`uvx`, nota onesta che il package non è ancora pubblicato; installazione locale riorganizzata in sezioni "Da locale" / "Per sviluppo".
+- **`--timeout` configurabile in CLI** (sesto punto): nuova opzione globale, stesso pattern di `--base-url` (override in `config.py`: `get_timeout()`/`set_timeout()`, usato come default da `client.rndt_request()`). Verificato live: `--timeout 0.5` contro un IP non instradabile fallisce in ~1.5s con messaggio leggibile ed exit 1 (no traceback), invece dei ~90s del default. 38/38 test, ruff e mypy verdi.
+- **v1.0.0** (ottavo punto, parziale su richiesta esplicita): `CHANGELOG.md` (Keep a Changelog), bump versione in `pyproject.toml`/`__init__.py`, classifier PyPI `3 - Alpha` → `5 - Production/Stable`, README aggiornato. Build 1.0.0 verificata (`uv build` + `twine check` PASSED, `py.typed` nel wheel). **Nessun push, tag o pubblicazione PyPI**: su richiesta dell'utente, questo giro si ferma al commit locale — tag/push/publish restano un passo successivo esplicito.
+- **Coverage 89%→99%** (settimo punto) e **bug reale trovato nel farlo**: `--format <valore-invalido>` produceva un traceback completo (verificato live) — violava il principio cardine "mai uno stack trace". Fix: `ValueError` di `output.set_mode()` ora catturato nel callback `_root` di `cli.py` → messaggio leggibile + exit 2. +17 test: `tests/test_output.py` nuovo (rami table/csv irraggiungibili dalla CLI, testati chiamando `output.emit()` direttamente); percorsi di successo mai testati a livello CLI (`get` default json, `get --html`, `get --format table`, `discover` in table); `search --format compact` zero risultati; payload di risposta non-dict; parametro `--modified`; `keywords_s` come stringa singola; download senza `dctype`. Aggiunto `pytest-cov` (dev) e fixture di reset per `output_mode`/`timeout` in `conftest.py` (stesso pattern di `_reset_base_url`). Coverage residua (99%, righe 230/234 di `cli.py`): solo `main()`/`__main__` boilerplate. 55/55 test, ruff e mypy verdi.
+
 ## 2026-06-11
 
 - **Nuovo formato `--format compact` (NDJSON per agenti).** Quarto formato di output per `search`: una riga JSON per record con i soli campi ad alto segnale (`id`, `title`, `org`, `type`, `category`, `updated`, `resources`). Pensato per far scremare molti risultati a basso consumo di token prima del `get`. Spunto dal progetto Copernicus-Services-Products-Metadata (rendering sintetico dei risultati; lì *prima* della ricerca perché catalogo locale, qui *dopo* perché catalogo remoto).

README.md

@@ -3,7 +3,7 @@
 CLI Python e libreria per accedere al **Repertorio Nazionale dei Dati Territoriali (RNDT)** —
 pensata per essere orchestrata da un'AI.
 
-> Stato: alpha (v0.1) — read-only.
+> Stato: v1.0 — read-only.
 
 ## Cos'è il RNDT
 
@@ -13,21 +13,36 @@ API per cercare e scaricare i metadati.
 
 ## Installazione
 
+### Da PyPI
+
+```bash
+uv tool install openrndt
+# oppure, senza installazione persistente:
+uvx openrndt --help
+```
+
+> Non ancora pubblicato su PyPI (roadmap verso la v1.0). Nel frattempo installa da locale.
+
+### Da locale
+
 ```bash
-# CLI globale (consigliato): venv isolato, eseguibile in PATH
-uv tool install /path/to/openrndt
+git clone https://github.com/ondata/openrndt.git
+cd openrndt
+
+# CLI globale: venv isolato, eseguibile in PATH
+uv tool install .
 
 # Aggiornamento dopo modifiche al codice
-uv tool install --reinstall /path/to/openrndt
+uv tool install --reinstall .
 
 # Disinstallazione
 uv tool uninstall openrndt
 ```
 
-Per sviluppo (modifiche con ricarica immediata):
+### Per sviluppo (modifiche con ricarica immediata)
 
 ```bash
-git clone <repo>
+git clone https://github.com/ondata/openrndt.git
 cd openrndt
 uv sync
 uv run openrndt --help
@@ -55,6 +70,13 @@ openrndt get age:D_E973_MARSAGLIA --xml > meta.xml
 openrndt discover
 ```
 
+Il timeout HTTP per singolo tentativo è configurabile con `--timeout` (default 30s);
+con i retry su timeout/5xx (3 tentativi) il caso peggiore è ~3x questo valore:
+
+```bash
+openrndt --timeout 5 search --q "catasto" --num 5
+```
+
 Tutti i comandi accettano `--format json` (default), `--format table`, `--format csv`.
 Per `search` c'è anche `--format compact`: una riga NDJSON per record con i soli
 campi ad alto segnale (`id`, `title`, `org`, `type`, `category`, `updated`,

docs/evaluation-v0.1.0.md

@@ -0,0 +1,49 @@
+# Valutazione openrndt v0.1.0 — readiness per produzione
+
+Data: 2026-07-17. Metodologia: lettura sistematica di `src/openrndt/` (7 moduli, 299 statement), esecuzione reale della suite test (`uv run pytest` + coverage con `pytest-cov`), build effettiva del package (`uv build` + `twine check`), esecuzione CLI live contro `https://geodati.gov.it/RNDT` (search reale, 8.827 risultati per "catasto"), test di percorsi d'errore (ID inesistente, parametro fuori range, host irraggiungibile, formato non tabellare). Valutazione indipendente, senza riferimenti a valutazioni precedenti.
+
+## Giudizio sintetico
+
+Il codice è solido, coerente e già production-grade nella sua logica applicativa: gestione errori disciplinata, test reali (non mock banali), doc allineata al comportamento verificato live. Quello che manca per una release pubblica non è nel codice ma nell'infrastruttura attorno: non c'è CI, non c'è type-checking automatizzato, il packaging PyPI ha lacune di metadata (repo non linkato, licenza in formato deprecato), e non esiste un blocco netto — è un progetto a un passo dalla v1.0, non a metà strada.
+
+## Punti di forza
+
+- **Gestione errori disegnata per agenti AI, verificata empiricamente**: mai uno stack trace, exit code distinti (0/1/2), messaggi su stderr. Confermato dai test live: ID inesistente → `exit 1` con messaggio leggibile; `--num 99999` → `exit 2`; `get --format csv` → rifiutato con messaggio esplicito senza chiamata di rete.
+- **Suite test reale**: 38 test, 89% coverage (`pytest --cov`), tutti mockati via `respx` (nessuna rete), copre retry (503×3 vs 503→200), JSON malformato con status 200, connessione rifiutata, formati di output incrociati.
+- **Documentazione insolitamente onesta e verificata sul campo**: `LOG.md` e `codelists.py` documentano bug reali dell'API RNDT scoperti live (`dataCategory` non filtra, `sort` "amichevole" ignorato, CSW non conforme INSPIRE) — non copiati dalla doc ufficiale ma testati.
+- **Doppio uso CLI/libreria reale**, non solo dichiarato: `from openrndt import search, get_item, ItemNotFoundError` funziona, eccezioni documentate nelle docstring, README ha sezione libreria dedicata con esempi.
+- **Build PyPI funzionante**: `uv build` produce wheel+sdist validi, `twine check` passa senza errori.
+- **Superficie di sicurezza minima e correttamente gestita**: `_encode_id()` usa `quote(safe="")`, i parametri passano per l'encoding httpx, l'API è read-only e il passthrough Lucene in `--q` è una feature intenzionale (documentata), non un vettore di injection.
+
+## Gap per la produzione
+
+### IMPORTANTE
+
+1. **Nessuna CI/CD** (`.github/` assente). Ogni merge si affida a run manuali locali. Fix: workflow GitHub Actions minimo — `uv sync && uv run pytest && uv run ruff check .` su push/PR, matrice 3.12/3.13.
+2. **Metadata PyPI incompleti per un consumo di terzi** — `pyproject.toml:33-35`: `[project.urls]` punta solo al portale dati e alla pagina REST API; mancano `Repository`/`Issues`/`Changelog` verso `https://github.com/ondata/openrndt`. Fix: aggiungere `Repository` e `Issues`, mantenendo il link RNDT con etichetta chiara (es. `"RNDT Portal"`).
+3. **README con installazione solo locale** — `README.md:16-25`: `uv tool install /path/to/openrndt` presuppone un clone locale. Fix: aggiungere sezione "da PyPI" quando pubblicato, tenendo quella locale come "per sviluppo".
+4. **Nessun type-checking automatizzato**: `mypy`/`pyright` non installati né in `[dependency-groups].dev` (`pyproject.toml:37-43`). Il codice usa type hints ovunque ma nessuno li valida. Fix: aggiungere `mypy` (o `pyright`) al gruppo dev + step CI.
+5. **Timeout di rete potenzialmente lungo per un agente che orchestra la CLI** — `client.py:16,25-29`: `DEFAULT_TIMEOUT=30.0` + retry 3× con `wait_exponential(max=10)` su `TimeoutException` può far attendere fino a ~90 secondi prima di un errore leggibile su un host lento/irraggiungibile (verificato empiricamente). Nessun flag CLI per abbassare timeout/retry. Fix: esporre `--timeout` (il parametro esiste già nella funzione, manca solo il flag CLI) e/o ridurre il default per la CLI interattiva.
+6. **Manca `py.typed`** (PEP 561): assente sia in `src/openrndt/` che nel wheel buildato. Per un package pensato anche come libreria, i tipi non sono distribuiti a chi lo importa. Fix: aggiungere file vuoto `src/openrndt/py.typed` e verificarne la presenza nel wheel al prossimo build.
+7. **Nessun CHANGELOG** separato da `LOG.md`. `LOG.md` è un diario di sviluppo, non un changelog utile a chi aggiorna la versione. Fix: `CHANGELOG.md` in formato Keep-a-Changelog, popolato almeno al primo tag di release.
+
+### NICE-TO-HAVE
+
+8. **Stato globale mutabile in `config.py` e `output.py`** (`config.py:10,19-21`; `output.py:14,18-22`): `_override` e `_output_mode` sono variabili modulo-livello. Irrilevante per la CLI; race condition latente per uso libreria in contesto concorrente. Da documentare come limite.
+9. **Nessun client HTTP condiviso**: `client.py:32` apre una nuova connessione a ogni chiamata (niente keep-alive/pooling). Trascurabile per la CLI, penalizzante per molte chiamate in sequenza da libreria.
+10. **Licenza in formato deprecato da PEP 639** — `pyproject.toml:9`: `license = { text = "MIT" }` è la forma legacy; la raccomandata è `license = "MIT"` (stringa SPDX). Fix banale.
+11. **Versione duplicata**: `__version__` in `__init__.py:7` e `version` in `pyproject.toml:3` da tenere sincronizzate a mano. Fix: derivare l'una dall'altra (es. `importlib.metadata.version()`).
+12. **Copertura test non uniforme**: `output.py` al 71% (branch `table` senza `table_rows`, rami `csv` vuoti); `cli.py` all'87% (`search --format compact` con 0 risultati, `discover` non-json per sezione singola, `main()`). Nessun percorso critico, ma vale la pena chiudere prima di v1.0.
+13. **`ref/` e `PRD.md` senza indice**: utili per chi sviluppa, non arrivano al consumatore PyPI (correttamente esclusi dal wheel).
+
+## Roadmap consigliata verso v1.0
+
+1. Aggiungere `py.typed`, verificare la sua presenza nel wheel dopo build.
+2. Aggiungere `mypy` (o `pyright`) al gruppo dev, far passare pulito.
+3. Creare `.github/workflows/ci.yml`: `uv sync`, `pytest`, `ruff check`, matrice 3.12/3.13.
+4. Sistemare `[project.urls]`: aggiungere `Repository`/`Issues`, chiarire il link RNDT come portale dati.
+5. Aggiornare README con installazione da PyPI accanto a quella locale per sviluppo.
+6. Esporre `--timeout`/retry configurabili in CLI.
+7. Chiudere i gap di coverage residui in `output.py`/`cli.py`.
+8. Aggiungere `CHANGELOG.md`, taggare `v1.0.0`, pubblicare su PyPI (`uv build` + `uv publish`).
+9. Facoltativo: migrare la licenza alla forma stringa SPDX; automatizzare `__version__` da un'unica fonte.

knowledge/api/index.md

@@ -0,0 +1,4 @@
+# API RNDT
+
+* [API REST del RNDT](rndt-rest-api.md) - endpoint usati da openrndt, parametri, campi Lucene.
+* [Bug noti e divergenze dalla documentazione ufficiale](known-issues.md) - comportamenti reali verificati live.

knowledge/api/known-issues.md

@@ -0,0 +1,29 @@
+---
+type: Reference
+title: Bug noti dell'API RNDT
+description: Divergenze verificate live tra la documentazione ufficiale RNDT e il comportamento reale dell'API.
+tags: [rndt, bug, verificato-live]
+timestamp: 2026-07-17T00:00:00Z
+---
+
+Tutti i punti seguenti sono stati verificati empiricamente contro l'API di produzione, non dedotti dalla documentazione. openrndt li compensa dove possibile.
+
+# Divergenze
+
+| Comportamento documentato | Comportamento reale | Compensazione in openrndt |
+|---------------------------|---------------------|---------------------------|
+| Il parametro `dataCategory` filtra per categoria. | Non filtra: ritorna sempre il catalogo intero. | `--data-category` è tradotto nella clausola Lucene `q=keywords_s:VAL` (`OR` per valori multipli). |
+| `sort=dateDescending` / `dateAscending` ordinano per data. | Ignorati: ordine identico fra loro. | `discover --what sort_values` marca i valori rotti; la sintassi funzionante è `campo:asc\|desc` su campo sortable (es. `apiso_Modified_dt:desc`). |
+| — | Ordinare su un campo `text` analizzato (es. `title` nudo) dà errore Elasticsearch "Fielddata is disabled". | Documentato nelle codelist; usare i campi `_s`/`_dt`/`_i`. |
+| Esiste una data di pubblicazione ordinabile. | Non esiste; `apiso_CreationDate_dt` è spesso null o fittizia (es. 2012-01-01). | Proxy consigliato per "più recenti": `apiso_Modified_dt:desc` (issue #4 del repository). |
+| L'endpoint CSW supporta `SortBy` (INSPIRE Discovery Services v3.1). | `SortBy` ignorato: non conforme. | Nessuna: documentato (issue #5 del repository). |
+| Item inesistente → errore HTTP. | Risponde `200` con body `{"found": false}`. | `get_item` controlla `found` e solleva `ItemNotFoundError`. |
+
+# Problemi di qualità dei dati (non dell'API)
+
+- Alcuni record dichiarano una bbox errata che copre tutta l'Italia (`6.6,35.5,18.5,47.1`): compaiono come rumore in qualunque ricerca `--bbox`. Il filtro bbox in sé funziona (semantica overlaps, verificata).
+
+# Citations
+
+[1] `ref/rest-api-rndt.md` e `LOG.md` nel repository (verifiche live datate).
+[2] [Pagina ufficiale REST API RNDT](https://geodati.gov.it/geoportale/eng/strumenti-en/rest-api)

knowledge/api/rndt-rest-api.md

@@ -0,0 +1,41 @@
+---
+type: External API
+title: API REST del RNDT
+description: Gli endpoint del geoportale RNDT usati da openrndt e i campi Lucene interrogabili.
+resource: https://geodati.gov.it/RNDT
+tags: [rndt, rest, elasticsearch, lucene]
+timestamp: 2026-07-17T00:00:00Z
+---
+
+Il RNDT espone un'API REST in stile Esri Geoportal Server su base `https://geodati.gov.it/RNDT` (configurabile via env `OPENRNDT_BASE_URL`). È read-only e senza autenticazione. openrndt applica retry esponenziale (3 tentativi) su timeout e 5xx.
+
+# Endpoint usati
+
+| Endpoint | Uso in openrndt |
+|----------|-----------------|
+| `GET /rest/metadata/search` | [search](/cli/search.md). Parametri: `q` (Lucene), `bbox`, `time`, `modified`, `sort`, `start`, `num` (max 5000), `f` (formato), `id`. |
+| `GET /rest/metadata/item/{id}` | [get](/cli/get.md), JSON Elasticsearch. |
+| `GET /rest/metadata/item/{id}/xml` | XML ISO 19139. |
+| `GET /rest/metadata/item/{id}/html` | HTML. |
+
+# Campi Lucene principali (parametro `q`)
+
+L'elenco completo con descrizioni è offline in [discover --what lucene_fields](/cli/discover.md). Regole sui suffissi:
+
+| Suffisso | Tipo | Note |
+|----------|------|------|
+| `_txt` | testo analizzato | wildcard trailing OK (`palerm*`), leading non supportata su campo esplicito. |
+| `_s` | keyword, case-sensitive | wildcard solo trailing. |
+| `_dt` | data ISO 8601 | range `[2024-01-01T00:00:00Z TO *]`; sortable. |
+| `_i` | intero | range `[1 TO 10000]`. |
+| `_b` | booleano | `true` \| `false`. |
+
+Campi ad alto valore: `apiso_Type_s` (dataset/series/service), `apiso_TopicCategory_s`, `apiso_OrganizationName_txt`, `apiso_Modified_dt`, `isOpendata` (`isOpendata:*` per tutti gli open data), `apiso_Format_s`, `INSPIRETheme_s`, `AmbitoTerritoriale_s`.
+
+Molti comportamenti reali divergono dalla documentazione ufficiale: vedi [bug noti](/api/known-issues.md).
+
+# Citations
+
+[1] [Pagina ufficiale REST API RNDT](https://geodati.gov.it/geoportale/eng/strumenti-en/rest-api)
+[2] [Spec Esri Geoportal Server](https://gpt.geocloud.com/geoportal3/api/gpt_api.json)
+[3] Mirror locale della documentazione: `ref/rest-api-rndt.md` nel repository.