worklimate

CLI per leggere i dati di stress da caldo di Worklimate: trova la stazione più vicina, consulta la previsione a 3 giorni e ricostruisci lo storico stagionale.

Pensata per essere usata sia da terminale (tabella colorata) sia orchestrata da un LLM / script (JSON e CSV stabili, comandi componibili).

• 🔌 Nessuna autenticazione — usa gli endpoint pubblici di app.worklimate.it e archivio.worklimate.it
• 🌍 Geocoding automatico via Nominatim / OpenStreetMap (digiti "palermo", non le coordinate) — attribuzione e uso corretto
• 🤖 Output machine-friendly di default quando non sei in un terminale (pipe, script, agent)

Installazione

npm install -g @aborruso/worklimate

Oppure senza installare nulla:

npx @aborruso/worklimate now palermo

Richiede Node.js ≥ 18.

Quickstart

worklimate search palermo          # stazione Worklimate più vicina
worklimate now palermo             # previsione rischio caldo: oggi + 2 giorni
worklimate now 305688              # …oppure direttamente per ID stazione (pgrid)
worklimate history palermo         # storico da inizio stagione (28 apr) a oggi
worklimate history palermo --from 2026-07-01 --to 2026-07-13

Comandi

search <luogo>

Geocoding + stazione più vicina. Restituisce pgrid (ID stazione), coordinate, distanza, altitudine, zona costiera.

now <luogo | pgrid>

Previsione del rischio da caldo per 3 giorni: oggi, domani, dopodomani. Ogni giorno ha data, colore, etichetta (Basso / Moderato / Alto / Emergenza) e consiglio.

• Se l'argomento è numerico (es. 305688) → interrogazione diretta alla stazione.
• Se è testo (es. palermo) → geocoding + stazione più vicina.

history <luogo> [--from YYYY-MM-DD] [--to YYYY-MM-DD]

Storico giornaliero del livello di rischio.

• --from default 2026-04-28 (primo giorno con dati Worklimate). Se passi una data precedente, viene clampata al 2026-04-28 con un warning.
• --to default oggi.

Formati di output

La CLI sceglie in automatico in base al contesto:

• Terminale interattivo (TTY) → tabella colorata
• Pipe / script / LLM (non-TTY) → JSON

Puoi forzare il formato con:

• --json — JSON strutturato (ideale per jq e agent AI)
• --csv — CSV con header
• --table — tabella forzata anche in pipe

Precedenza: --json > --csv > --table > auto.

Schema JSON (per orchestrare con un LLM)

Tutti gli output JSON hanno uno schema stabile e prevedibile.

search

{
  "luogo": "Palermo",
  "display_name": "Palermo, Sicilia, Italia",
  "lat": "38.1112268",
  "lon": "13.3524434",
  "pgrid": 305688,
  "distanza_km": 1.3,
  "stazione": { "lat": "38.12", "lon": "13.36", "alt_m": 102, "costa": true }
}

now

{
  "pgrid": 305688,
  "giorni": [
    {
      "data": "2026-07-13",
      "giorno_settimana": "lunedì",
      "colore": "red",
      "label": "Alto",
      "desc": "…",
      "longdesc": "…"
    }
  ]
}

history

{
  "pgrid": 305688,
  "dal": "2026-04-28",
  "al": "2026-07-13",
  "giorni": [
    { "data": "2026-04-28", "giorno_anno": 118, "colore": "yellow" }
  ]
}

Valori possibili di colore: green (Basso), yellow (Moderato), orange (Alto), red (Emergenza).

Esempi di orchestrazione

Componi i comandi a step — l'output di uno alimenta il successivo:

# 1. scopri la stazione più vicina e prendi il pgrid
PGRID=$(worklimate search palermo --json | jq -r .pgrid)

# 2. consulta la previsione a 3 giorni di quella stazione
worklimate now "$PGRID" --json

# 3. export dello storico in CSV per analisi
worklimate history palermo --csv > palermo-storico.csv

Un agent AI può quindi: leggere il luogo dell'utente → search per ottenere pgrid → now/history → formattare la risposta. Ogni comando fa una cosa sola.

Comportamento in caso di errore

• Luogo non trovato, HTTP non 200, JSON non valido → messaggio chiaro su stderr, exit code 1, stdout vuoto (così l'AI non riceve dati sporchi).
• Warning tecnici (es. clamp della data) → su stderr, non inquinano stdout.
• Nessuno stack trace esposto.

Fonte dei dati

I dati provengono dagli endpoint pubblici (AJAX) di Worklimate:

• https://app.worklimate.it/osm-stazioni.php — stazione vicina e previsione a 3 giorni
• https://archivio.worklimate.it/ajax-stazioni.php — storico

Nessuna chiave API necessaria. I dati di rischio sono disponibili dalla stagione calda (fine aprile).

Geocoding, Nominatim e OpenStreetMap

Il geocoding (nome luogo → coordinate) usa l'istanza pubblica Nominatim gestita dalla OpenStreetMap Foundation, che interroga i dati di OpenStreetMap.

Attribuzione — i risultati del geocoding sono derivati da dati OpenStreetMap:

© OpenStreetMap contributors

I dati OpenStreetMap sono rilasciati sotto licenza ODbL. Vedi https://www.openstreetmap.org/copyright. La CLI mostra l'attribuzione ogni volta che esegue un geocoding: su stderr (search, now <luogo>, history <luogo>), in calce alla tabella e nel campo attribution del JSON di search.

Uso corretto (Nominatim Usage Policy) — la CLI rispetta la usage policy dell'istanza pubblica:

• invia uno User-Agent identificativo (worklimate/<versione>), non un UA generico;
• effettua una sola richiesta per esecuzione, ben entro il limite di 1 richiesta/secondo.

Questo strumento non è pensato per geocoding massivo o sistematico. Per volumi elevati, o per un uso di produzione, ospita una tua istanza Nominatim o usa un provider di geocoding a pagamento: l'istanza pubblica è una risorsa condivisa a titolo gratuito. La CLI non conserva una cache tra esecuzioni (una richiesta per processo); se ne integri il codice in loop su molti luoghi, aggiungi tu una cache come richiesto dalla policy.

Sviluppo

git clone https://github.com/aborruso/worklimate.git
cd worklimate
npm install
node src/cli.js now palermo --table

Struttura:

src/
  cli.js      # entry (Citty): main + subcomandi + flag
  api.js      # chiamate HTTP a Worklimate + Nominatim
  format.js   # risoluzione formato (TTY-aware) + rendering table/json/csv

Release

Release manuale, senza CI. Vedi docs/design.md per le decisioni architetturali.

npm version patch            # bump versione
npm pack --dry-run           # verifica contenuto tarball
npm publish --access public  # pubblicazione (scoped)
git push --tags
gh release create vX.Y.Z --notes "..."

Licenza

MIT © Andrea Borruso

I dati appartengono a Worklimate; questa CLI è un client non ufficiale che legge gli endpoint pubblici.