Manutenzione

Cadenza consigliata

Cosa	Ogni	Comando / azione
Dipendenze npm	mese	`npm outdated`, `npm update`, `npm run quality`
Astro (major)	~anno	leggere le note di migrazione, aggiornare, rifare il gate
Starlight (guida)	con Astro	`cd guide && npm update && npm run build`
WordPress core + plugin	settimana	backup prima, poi aggiorna
Node in CI	quando Astro lo richiede	`node-version` nei workflow
Test manuale form/consenso	a ogni release	invio reale, cookie, mappa

Aggiornare le dipendenze

npm outdated
npm update
npm run quality

Se npm update rompe la build:

leggi l’errore: quasi sempre è un contratto dati o una breaking change di Astro;
aggiorna una major alla volta;
non aggiornare “alla cieca” Tailwind o Astro senza rileggere la config.

La guida ha un package.json separato: aggiornala a parte.

Il contratto dati è la parte fragile

Ogni volta che cambi un campo in WordPress devi aggiornare quattro punti:

wordpress/mu-plugins/headless-cms.php (registrazione e metabox);
src/cms/wordpress/wordpress-*.schema.ts (Zod);
src/cms/wordpress/wordpress-*.mapper.ts (+ dominio se serve);
tests/fixtures/*.json e il test.

Se te ne dimentichi uno, il fallimento arriva in build (bene) o in produzione (male). Prima di deployare un cambio di contratto: ENABLE_HTML_FALLBACK=false in locale, così riproduci la CI.

WordPress

Backup di file e database prima di ogni aggiornamento.
Aggiorna core, temi (se presenti) e plugin. Il frontend non usa il tema, quindi un tema rotto non rompe il sito pubblico, ma può rompere l’admin.
Non installare page builder o plugin che alterano la REST.
Controlla che i mu-plugin siano ancora presenti dopo migrazioni/ripristini.
Rigenera i permalink dopo aver aggiunto o rinominato un CPT.

Sicurezza

Token GitHub (HEADLESS_WEBHOOK_PAT) fine-grained, solo su questo repository, Contents: Read and write; ruotalo se sospetti una fuga.
Nessun segreto nel repository: .env.local è ignorato, i secrets stanno su GitHub.
2FA sull’account GitHub e sull’admin WordPress.
Limita i tentativi di login (plugin) e disattiva XML-RPC (già fatto).
Aggiorna PHP su hosting quando disponibile (8.1+).

Contenuti

Immagini: caricare file già ridimensionati (lato ~1600px, <300 KB) e con alt.
Campi JSON: validare la sintassi; WordPress rifiuta il salvataggio se è malformata.
Categorie eventi: devono combaciare con site.eventCategories.
Testi legali: URL in Impostazioni sito, non hardcoded nel footer.
Non usare l’editor WordPress per testi strutturali del layout: diventano campi.

Monitoraggio

Build: notifiche GitHub fallite via email/Slack; un deploy rosso significa sito fermo alla versione precedente.
Uptime: ping su home e /contatti.
Search Console: 404, copertura, sitemap.
Form: verifica periodica che le mail arrivino (SPF/DKIM sull’hosting).
Prestazioni: Lighthouse su mobile dopo ogni modifica importante.

Debito noto (accettato)

per_page=100 senza paginazione: oltre 100 elementi per CPT vengono troncati. Upgrade path in Build e concorrenza.
Nessuna preview editoriale: si vede dopo il rebuild.
Nessuna cache REST tra build: ~14 richieste per build, accettabile.
Guida su Pages: richiede repo pubblico o piano pagato.
Nessun test E2E nel browser: i test coprono schema, loader e helper date.

Ogni debito ha un motivo. Se un progetto lo rende inaccettabile, si affronta con una decisione esplicita, non con una toppa silenziosa.