@elia97/officina 0.10.0 → 0.12.0

package/README.md

@@ -19,6 +19,8 @@ pnpm add -D @elia97/officina
     "check:roadmap": "officina check roadmap",
     "check:placeholders": "officina check placeholders",
     "perf:bundle": "officina check bundle",
+    "check:links": "officina check links",
+    "check:secrets": "officina check secrets",
     "smoke:prod": "officina check smoke",
     "analytics:verify": "officina check analytics",
     "lhci": "officina check lighthouse",
@@ -38,14 +40,16 @@ I gate leggono dalla cartella corrente, che deve essere la radice del repository
 
 `check language` vuole in italiano i commenti del codice e i Markdown di documentazione. Lascia fuori per intero ciò che non è documentazione del progetto: i dizionari di `src/i18n/strings/` e i Markdown sotto `src/content/`, che sono copy nelle lingue del sito; le fonti del cliente in `docs/sources/`; i `CHANGELOG.md`, generati in inglese. Un file YAML di `src/content/` invece è codice, e i suoi commenti si controllano come altrove.
 
-`check routes` segue i rimandi dei Markdown del progetto: i percorsi fra apici inversi dentro `docs`, `src`, `scripts`, `test`, `e2e`, `public`, `.claude` e `.github`; i rimandi a una sezione, nella forma `file.md` § Titolo; i link e le immagini con una destinazione relativa, anche a riferimento e verso una cartella; e due tipi di nomi senza cartella, i documenti in maiuscolo come `HOW_TO_USE.md`, cercati accanto a chi cita, alla radice e in `docs/`, e i file di configurazione che vetrina tiene alla radice, come `vercel.json`. Un link che esce dal repository è un rimando morto, perché in CI la cartella sopra non c'è. Restano fuori gli altri nomi senza cartella, come `head.astro`, gli URL, le ancore, il codice negli span e nei blocchi recintati, un nome che fa da testo a un link, dove conta la destinazione, i link e i nomi dei Markdown di `src/content/`, che sono copy del sito, e i nomi citati in `docs/ROADMAP.md` e nei `CHANGELOG.md`, che raccontano documenti usciti o da scrivere. Un blocco rientrato di quattro spazi non si riconosce come codice: un esempio va in un blocco recintato.
+`check routes` segue i rimandi dei Markdown del progetto: i percorsi fra apici inversi dentro `docs`, `src`, `scripts`, `test`, `e2e`, `public`, `drizzle`, `.claude` e `.github`; i rimandi a una sezione, nella forma `file.md` § Titolo; i link e le immagini con una destinazione relativa, anche a riferimento e verso una cartella; e due tipi di nomi senza cartella, i documenti in maiuscolo come `HOW_TO_USE.md`, cercati accanto a chi cita, alla radice e in `docs/`, e i file di configurazione che vetrina tiene alla radice, come `vercel.json`, più `drizzle.config.ts` dei progetti con un database. Un link che esce dal repository è un rimando morto, perché in CI la cartella sopra non c'è. Restano fuori gli altri nomi senza cartella, come `head.astro`, gli URL, le ancore, il codice negli span e nei blocchi recintati, un nome che fa da testo a un link, dove conta la destinazione, i link e i nomi dei Markdown di `src/content/`, che sono copy del sito, e i nomi citati in `docs/ROADMAP.md` e nei `CHANGELOG.md`, che raccontano documenti usciti o da scrivere. Un blocco rientrato di quattro spazi non si riconosce come codice: un esempio va in un blocco recintato.
 
 ## Verifiche di build e di produzione
 
 | Comando | Cosa guarda | Da dove prende le rotte |
 |---|---|---|
 | `check bundle` | il JavaScript e il CSS di `dist/client`, gzip, contro un budget per rotta | `src/pages`; sotto SSR, il manifest della build Vercel |
-| `check smoke [url]` | la produzione viva: pagine, header di sicurezza, BotID, host canonico, barra finale | `src/pages`, più le rotte non HTML |
+| `check links` | gli `<a href>` di `dist/client`: ogni link interno porta a qualcosa che la build serve, e nessuno a `#` | i file di `dist/client` e le rotte a richiesta del manifest della build Vercel |
+| `check secrets [--canaries]` | i file di `dist/client`: nessuno contiene il valore o il canary di una chiave server e secret di `env.schema` | — |
+| `check smoke [url]` | la produzione viva: pagine, pagine rese a richiesta, header di sicurezza, BotID, host canonico, barra finale | `src/pages`, più le rotte non HTML |
 | `check analytics [GTM-…]` | il container GTM pubblico contro gli eventi del modulo di link-tracking del progetto (`analytics.linkTracking`) | — |
 | `check lighthouse [url] [--local]` | Lighthouse CI sul `.lighthouserc.json` del progetto; con `url` misura un sito già servito, `--local` fa build, server statico e Chrome da sé | `src/pages` |
 | `gen icons` | le icone del manifest, disegnate da `public/favicon.svg`, che è il suo ingresso obbligatorio | — |
@@ -54,10 +58,18 @@ Gli script di una pagina statica si leggono dal suo HTML, anche sotto una `base`
 
 Il CSS di una rotta è la somma dei fogli di `dist/client/_astro` che collega, ognuno contato una volta: per una pagina statica i `<link rel="stylesheet">` del suo HTML, anche sotto una `base`, da un `assetsPrefix` o con una query; per una rotta renderizzata a richiesta i fogli esterni che il manifest le assegna, e una rotta per cui il manifest non li dice è un fallimento. Il tetto è `bundle.cssMaxGzip`, e il rapporto ha una riga per ogni combinazione di fogli, perché le rotte che collegano gli stessi fogli pesano uguale. Non si contano il CSS dentro l'HTML, nei `<style>`, come il JavaScript incorporato, i link che non bloccano il rendering (`preload`, `prefetch`) e i fogli fuori da `_astro`, da `public/` o da un CDN. Un foglio citato che in `_astro` non c'è è un fallimento. Un foglio che nessuna rotta misurata collega si pesa da solo contro lo stesso tetto, e nel rapporto porta «da solo»: il CSS di un `import()` dinamico, quello dei componenti dentro un contenuto MDX reso a richiesta, che il manifest non assegna alla pagina, o tutti i fogli di una build le cui rotte non si leggono. Da solo pesa meno del vero, ma nessun foglio oltre il tetto passa in silenzio.
 
+`check links` legge gli `<a href>` di ogni HTML di `dist/client`, fuori dai commenti, dagli `<script>`, dagli `<style>` e dai valori degli attributi, dove Astro lascia `<` e `>` come sono. È interno un link relativo, uno che comincia con `/` o uno assoluto verso l'origine di `siteUrl`, e se ne confronta il percorso, senza query né ancora, con o senza barra finale; un link relativo si risolve come con `trailingSlash: 'never'`, che è quello dei template. Vale se porta a un file della build, pagina o altro file, o a una rotta che il manifest della build Vercel rende a richiesta, endpoint e `/` di lingua compresi, confrontata con il pattern che Astro scrive lì; senza manifest, o con un altro adapter, a una pagina `.astro` con `prerender = false`, e il rapporto lo dice. Che la pagina dietro una rotta a richiesta esista lo sa solo il server, e una rotta come `/[...slug]` accetta ogni percorso: il rapporto conta i link che passano così. `href="#"`, `href=""` e un `href` senza valore sono segnaposto, e falliscono come un link rotto. Il rapporto raggruppa per destinazione e nomina le pagine che la citano: un link rotto nel footer è un problema solo, non uno per pagina. Restano fuori, e il rapporto li conta, i link esterni, che chiederebbero la rete, `mailto:`, `tel:` e gli altri schemi, e l'id a cui punta un'ancora. Una `dist/client` senza HTML è un fallimento, perché il controllo non affermerebbe niente: un progetto che rende ogni pagina a richiesta lo spegne con `features.links: false`. Due limiti: con una `base` i link non si risolvono, e un redirect di `vercel.json` non è una pagina, quindi un link che ci porta passa per rotto, e si corregge puntando alla destinazione.
+
+`check secrets` legge le chiavi di `env.schema` con `context: 'server'` e `access: 'secret'`, dal sorgente di `astro.config.mjs` come `doctor`, e le cerca in ogni file di `dist/client`: un import sbagliato basta a portare un segreto nel browser. Per ogni chiave cerca il valore che ha nell'ambiente, anche nelle forme in cui Astro lo scrive nel markup e negli script, e il suo canary, `officina-<CHIAVE>-canary`, che `--canaries` stampa come righe `CHIAVE=valore` da mettere nell'ambiente della build. `actions/ci` lo fa dopo `pnpm run ci`, così i test che `ci` lancia non vedono i canary e la build sì. Il canary si dà solo ai campi `envField.string` senza validazioni (`max`, `min`, `length`, `url`, `includes`, `startsWith`, `endsWith`), perché Astro valida ogni variabile sul suo tipo e su quelle, e un canary che non le rispetta fermerebbe la build: una chiave così, in CI, resta da verificare. Una chiave che compare in un file è un fallimento che nomina la chiave e il file. Una chiave senza valore né canary nell'ambiente, o con un valore di meno di 8 caratteri, che cercato darebbe falsi positivi, non si verifica: il rapporto la dice con un avviso, invece di contarla fra le verificate. Uno schema senza chiavi segrete non ha niente da verificare, e una `dist/client` vuota è un fallimento.
+
 Per Lighthouse un sito SSR si misura con `check lighthouse <url>`, sulla produzione o su un'anteprima: al posto del server del progetto visita quell'indirizzo, ed è l'unico modo di avere numeri di produzione. `--local` serve i file statici della build, quindi su un sito renderizzato a richiesta si ferma e lo dice, invece di misurare dei 404. Un'anteprima Vercel con la Deployment Protection risponde con la pagina di accesso, e il check non la può misurare: serve la produzione o un'anteprima non protetta. La porta del server locale segue `LH_PORT` sia con `--listen` sia con `--port`.
 
 Lo smoke legge gli header di sicurezza sulla pagina a cui arriva la radice. Se `/` è un redirect sulla stessa origine — il 302 di lingua che Astro emette con `i18n.routing.redirectToDefaultLocale`, per esempio — li cerca sulla destinazione, perché il redirect non porta la CSP delle pagine renderizzate, e il nome del controllo dice dove li ha letti: `header content-security-policy su /it`. Un redirect verso un'altra origine, o senza `location`, è un fallimento. Anche l'attesa che l'alias di produzione punti al deployment nuovo conta un 3xx come una risposta.
 
+Lo smoke visita anche le pagine rese a richiesta, quelle di `src/pages` con `export const prerender = false`. Ognuna risponde 200, oppure con un redirect sulla stessa origine, come una pagina protetta che rimanda all'accesso; un 200 è HTML e porta il meta `Content-Security-Policy` con la direttiva `script-src`, quello che il middleware dei template scrive nelle pagine rese a richiesta. Una pagina dinamica si visita col suo rappresentante di `routes.representatives`, altrimenti si salta dicendolo. Queste pagine non entrano nel controllo della barra finale né in Lighthouse. Nella 0.12.0 un'anomalia è un avviso, che lo smoke stampa con `·` senza fallire; dalla 0.13.0 sarà un fallimento. officina riconosce una pagina resa a richiesta dalla dichiarazione: con `output: 'server'`, una pagina senza `prerender = false` resta per tutti i gate una pagina prerenderizzata, e lo smoke la visita come le altre, senza cercarne la CSP.
+
+Quando fallisce, lo smoke dice che la produzione è online e rotta, e consiglia di tornare indietro dalla dashboard di Vercel promuovendo l'ultimo deployment di produzione sano. Con `features.database` accesa aggiunge che lo schema non torna indietro: le migrazioni già applicate restano, e il deployment promosso regge solo se sono compatibili con il suo codice, la regola di «Migrazioni compatibili con la produzione» in § Action per i workflow.
+
 Il motore è uguale per tutti; ciò che cambia da un progetto all'altro sta in un file solo, `officina.config.ts` nella radice:
 
 ```ts
@@ -74,7 +86,7 @@ export default defineConfig({
   icons: { background: SITE.themeColor.light },
   bundle: { budgets: [motion], cssMaxGzip: 14 * 1024 },
   smoke: { checks: [...DEFAULT_CHECKS, checkLanguageRedirect] },
-  features: { analytics: 'required', roadmap: false, botId: 'required' },
+  features: { analytics: 'required', roadmap: false, botId: 'required', links: 'required' },
   routes: { representatives: { '/blog/[slug]': '/blog/ciao-mondo' } },
 })
 ```
@@ -83,7 +95,7 @@ La radice del pacchetto esporta `defineConfig` e i tipi; i pezzi del motore stan
 
 | Sottopercorso | Cosa esporta |
 |---|---|
-| `@elia97/officina/smoke` | `DEFAULT_CHECKS`, i cinque controlli, `SECURITY_HEADERS`, `NON_HTML_ROUTES` |
+| `@elia97/officina/smoke` | `DEFAULT_CHECKS`, i sei controlli, `SECURITY_HEADERS`, `NON_HTML_ROUTES` |
 | `@elia97/officina/bundle` | `CSS_BUDGET_GZIP` |
 | `@elia97/officina/icons` | `ICON_SPECS` |
 
@@ -91,11 +103,15 @@ La radice del pacchetto esporta `defineConfig` e i tipi; i pezzi del motore stan
 
 `features` dice quali controlli il progetto pretende: `'required'` fa fallire il gate quando ciò che deve guardare non c'è, `false` lo spegne dicendolo. Per BotID è `features.botId`: con `false` lo smoke salta la challenge e lo scrive nell'uscita, anche dentro una lista di `smoke.checks` che la contiene. Una voce non dichiarata vale `'required'`, e `doctor` la segnala: un gate che esce 0 su un container GTM che non esiste non afferma niente. `routes.representatives` dà a ogni pattern dinamico di `src/pages` un percorso vero, e da lì smoke e Lighthouse guardano anche quelle pagine.
 
+`routes.disabled` elenca i pattern dinamici che il progetto spegne per scelta, scritti come le chiavi di `routes.representatives`: le news tenute spente finché non ci sono articoli veri, con un `getStaticPaths` che non emette niente. Come per `features`, una pagina si spegne scrivendolo, non dimenticandola: un pattern dinamico che non emette niente senza essere dichiarato resta un fallimento di `check bundle`. Su un pattern spento `check bundle` non pretende pagine e lo elenca come spento, `doctor` non chiede il rappresentante e lo elenca fra le spente, smoke e Lighthouse non lo visitano, anche se il rappresentante c'è ancora, e lo scrivono nell'uscita: quando il progetto riaccende la pagina, qui basta togliere la voce. Il contrario è un fallimento di `check bundle`, perché dichiarazione e build non coincidono: una rotta emessa che soltanto un pattern spento spiega, o una pagina spenta che la build rende a richiesta, come una pagina senza `prerender` con `output: 'server'`. Si spegne solo una pagina prerenderizzata. `doctor` legge il sorgente, e una voce che lì non è una pagina dinamica prerenderizzata di `src/pages` è un suo errore: una pagina statica Astro la genera sempre, e un nome sbagliato non spegne niente. `check bundle` conosce solo le pagine `.astro`: una pagina Markdown di `src/pages`, o un `.html` di `public/`, che cade sotto un pattern spento passa per emessa da quello.
+
 `features.generators` ha un valore in più delle altre, perché non tutti i siti in produzione nascono dallo scaffold: `'required'` è il comportamento di sempre; `false` spegne i generatori del pacchetto, e `doctor` smette di chiedere i punti di aggancio e gli ancoraggi invece di pretendere file che nessun codice di quel sito userebbe; `'project'` fa lo stesso ma lascia vivi i generatori che il progetto scrive in `officina.generators.mjs`, che a quel punto `doctor` pretende. Con `false` o `'project'`, `officina gen section|page|component|collection` si ferma dicendolo, mentre gli script `gen` e `gen:*` restano attesi in `package.json`: meglio un comando che spiega di uno script che manca. `gen icons` non c'entra con i generatori di codice e non cambia.
 
-`placeholders` dice a `check placeholders` cosa guardare: `sources` sono i file da scandire, `contactEnvKeys` le variabili che `--env` pretende. Una lista dichiarata **sostituisce** quella del pacchetto, dizionari compresi: senza dichiarazione i sorgenti sono `src/lib/site.ts`, `src/lib/company.ts` e i dizionari di `src/i18n/strings`, quando la cartella esiste. Serve ai progetti che non nascono dallo scaffold: se partita IVA, recapiti e destinatario dei form stanno nel contenuto invece che in un modulo, i sorgenti del template non sono i suoi, e crearli per far passare il gate terrebbe gli stessi dati in due sedi. Un sorgente elencato che non esiste è un ritrovamento con il suo percorso, non un errore che ferma il comando.
+`features.database` e `features.auth` sono le due voci che il silenzio non accende, perché la maggior parte dei progetti un database non lo ha: seguono le dipendenze. `database` è accesa quando `package.json` dipende da `drizzle-orm`, `auth` quando dipende da `better-auth`, fra le `dependencies` o le `devDependencies`; senza la libreria la voce non si chiede e vale spenta. Dichiarata, vale la dichiarazione: `false` spegne la feature anche con la libreria, e `doctor` lo scrive nell'uscita; `'required'` la accende anche senza. `database.migrationUrlKey` è la variabile con cui girano le migrazioni, `DATABASE_URL_UNPOOLED` se non è dichiarata, e deve essere il nome di una variabile d'ambiente.
+
+`placeholders` dice a `check placeholders` cosa guardare: `sources` sono i file da scandire, `contactEnvKeys` le variabili che `--env` pretende. Una lista dichiarata **sostituisce** quella del pacchetto, dizionari compresi: senza dichiarazione i sorgenti sono `src/lib/site.ts`, `src/lib/company.ts` e i dizionari di `src/i18n/strings`, quando la cartella esiste. Serve ai progetti che non nascono dallo scaffold: se partita IVA, recapiti e destinatario dei form stanno nel contenuto invece che in un modulo, i sorgenti del template non sono i suoi, e crearli per far passare il gate terrebbe gli stessi dati in due sedi. Un sorgente elencato che non esiste è un ritrovamento con il suo percorso, non un errore che ferma il comando. Con il database acceso `--env` pretende anche `DATABASE_URL`, e con l'autenticazione `BETTER_AUTH_SECRET`, qualunque sia `contactEnvKeys`: la variabile delle migrazioni no, perché al deploy arriva da un segreto di GitHub.
 
-Nel deploy `check placeholders` gira due volte sui file di Vercel. Con `--env .vercel/.env.production.local`, dopo `vercel pull`, distingue una chiave che su Vercel non esiste, una vuota e una che porta un segnaposto del template, tutte e tre errori, da una variabile **Sensitive**: `vercel pull` non ne scarica il valore e scrive al suo posto `[SENSITIVE]`, quindi il check lo dice con un avviso, che non ferma il deploy, invece di darla per verificata. Il segnaposto però diventa un problema se la build legge la variabile, per esempio una variabile di `astro:env` con `access: 'public'`, che Astro incorpora nel codice: con `--output .vercel/output`, dopo `vercel build`, il check cerca `[SENSITIVE]` nei file della build e ferma il deploy nominandoli. Una variabile che la build legge va tenuta Encrypted su Vercel, o letta a runtime.
+Nel deploy `check placeholders` gira due volte sui file di Vercel. Con `--env .vercel/.env.production.local`, dopo `vercel pull`, distingue una chiave che su Vercel non esiste, una vuota e una che porta un segnaposto del template, tutte e tre errori, da una variabile **Secret**: `vercel pull` non ne scarica il valore e scrive al suo posto `[SENSITIVE]`, quindi il check lo dice con un avviso, che non ferma il deploy, invece di darla per verificata. Il segnaposto però diventa un problema se la build legge la variabile, per esempio una variabile di `astro:env` con `access: 'public'`, che Astro incorpora nel codice: con `--output .vercel/output`, dopo `vercel build`, il check cerca `[SENSITIVE]` nei file della build e ferma il deploy nominandoli. Una variabile che la build legge va tenuta Config su Vercel, o letta a runtime, e una Secret non diventa Config: si toglie e si riaggiunge.
 
 Il file lo carica Node, che fuori da `node_modules` toglie i tipi da sé: niente `enum`, niente alias `@/`. Due file `officina.config.*` insieme sono un errore, come un file senza default export; il resto lo valida `loadConfig` a runtime, nominando il percorso della voce sbagliata — `bundle.cssMaxGzip: atteso un numero, ricevuto una stringa` — e una voce sconosciuta, perché `sitUrl` al posto di `siteUrl` non deve passare in silenzio.
 
@@ -126,15 +142,20 @@ I passi dei workflow stanno in `actions/` di questo repository, come composite a
 
 | Action | Passi | Cosa resta nel workflow del progetto |
 |---|---|---|
-| `actions/ci` | checkout, node, install, `astro sync`, `pnpm run ci`, build, `perf:bundle`; con `e2e: 'true'` anche Playwright | trigger, permessi, il job `ci` |
+| `actions/ci` | checkout, node, install, `astro sync`, con `migrate` le migrazioni del database della corsa, `pnpm run ci`, i canary di `check secrets`, build, `perf:bundle`, `check:links`, `check:secrets`; con `e2e: 'true'` anche Playwright | trigger, permessi, il job `ci`; con un database, il branch Neon della corsa, creato e cancellato intorno all'action, e lo script delle migrazioni e il suo indirizzo passati in `with:` |
 | `actions/review` | `astro sync`, poi `fallow review` sul diff contro il merge-base | il job informativo |
-| `actions/deploy` | risoluzione del tag, stessa versione di officina, gate, `vercel pull`, `build`, controllo della build, `deploy`, smoke; espone `url` | trigger, `environment`, i tre segreti Vercel passati in `with:`, il job che controlla se i segreti ci sono |
+| `actions/deploy` | risoluzione del tag, stessa versione di officina, gate, `vercel pull`, con `migrate` le migrazioni, `build`, controllo della build, `deploy`, smoke; espone `url` | trigger, `environment`, i tre segreti Vercel passati in `with:`, il job che controlla se i segreti ci sono; con un database, lo script delle migrazioni e il segreto `PRODUCTION_DATABASE_URL` passati in `with:` |
 | `actions/lighthouse` | build equivalente alla produzione e `pnpm run lhci` | trigger, etichetta, `continue-on-error` |
 
 ```yaml
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     environment:
       name: production
       url: ${{ steps.deploy.outputs.url }}
@@ -150,17 +171,70 @@ jobs:
 
 `astro sync` genera i tipi di `.astro/`, che fallow pretende e un checkout pulito non ha; se fallisce il passo lo segnala con un avviso e il job prosegue.
 
-I tre segreti sono input obbligatori e l'action li mette nell'`env` dei soli tre passi che chiamano `vercel`. Nell'`env` del job li vedrebbero anche `pnpm install` e gli script di installazione di ogni dipendenza, che girano codice di terzi con in mano un token di deploy.
+I tre segreti sono input obbligatori e l'action li mette nell'`env` dei soli tre passi che chiamano `vercel`, come `database-url` in quello delle migrazioni. Nell'`env` del job li vedrebbero anche `pnpm install` e gli script di installazione di ogni dipendenza, che girano codice di terzi con in mano un token di deploy o il database di produzione.
 
 **Il deploy lanciato a mano.** Con `workflow_dispatch` il workflow viene dal ramo scelto in «Use workflow from», e il pacchetto dal lockfile del tag che si deploya: le due metà possono avere due versioni di officina diverse, e un passo dell'action più nuova può chiamare un'opzione che gli script del tag non conoscono. `actions/deploy` confronta le due versioni subito dopo l'install, prima di ogni script del progetto e di `vercel pull`, e si ferma dicendole se non coincidono o se il tag non installa officina. Un tag più vecchio si deploya lanciando Deploy da quel tag: il suo `deploy.yml` dichiara l'action della sua versione, con i gate di allora. Perché si possa, l'environment `production` del progetto deve ammettere i tag fra i ref da cui si deploya.
 
+**Il database di test.** Ogni corsa della CI migra un database suo: un branch Neon che il `ci.yml` del progetto crea prima di `actions/ci`, figlio di un branch vuoto, e cancella alla fine. Così due corse in parallelo, come la CI di una PR e quella di `main`, non vedono l'una le migrazioni dell'altra. Il genitore resta vuoto perché il migratore di drizzle-orm 0.45 applica una migrazione solo se è più recente dell'ultima applicata: ogni corsa le applica tutte, da zero, e nessuna si salta.
+
+```yaml
+      - name: Branch Neon della corsa
+        id: neon
+        env:
+          NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+        run: |
+          [ -n "$NEON_API_KEY" ] || exit 0
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+          echo "expires=$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_OUTPUT"
+      - uses: neondatabase/create-branch-action@v6
+        id: branch
+        if: steps.neon.outputs.enabled == 'true'
+        with:
+          project_id: ${{ vars.NEON_PROJECT_ID }}
+          api_key: ${{ secrets.NEON_API_KEY }}
+          parent_branch: test
+          branch_name: ci-${{ github.run_id }}-${{ github.run_attempt }}
+          expires_at: ${{ steps.neon.outputs.expires }}
+      - uses: Elia97/officina/actions/ci@vX.Y.Z
+        with:
+          migrate: db:migrate
+          database-url: ${{ steps.branch.outputs.db_url }}
+      - uses: neondatabase/delete-branch-action@v3
+        if: always() && steps.branch.outputs.branch_id != ''
+        with:
+          project_id: ${{ vars.NEON_PROJECT_ID }}
+          branch: ${{ steps.branch.outputs.branch_id }}
+          api_key: ${{ secrets.NEON_API_KEY }}
+```
+
+Il genitore, `test` nell'esempio, è il branch di test di prima. Si svuota una volta con `DROP SCHEMA public CASCADE; CREATE SCHEMA public; DROP SCHEMA IF EXISTS drizzle CASCADE;`, e da lì nessuno lo migra. Il primo passo legge la chiave dal proprio `env`, non da quello del job, dove la vedrebbero anche le dipendenze. `expires_at` cancella il branch anche quando il passo finale non arriva. La chiave dell'API di Neon crea e cancella i branch del progetto, quindi va limitata al progetto dove Neon lo permette, e non va data a Dependabot, che la passerebbe al codice di ogni aggiornamento. `doctor` avvisa quando `ci.yml` passa ancora un branch condiviso, `TEST_DATABASE_URL`.
+
+Prima di `pnpm run ci` l'action lancia `officina migrate --script <migrate>`, che legge `database.migrationUrlKey` da `officina.config.ts` e dà l'indirizzo allo script sotto quella chiave, e solo sotto quella. `pnpm run ci` lo riceve come `TEST_DATABASE_URL`, per i test di integrazione. La build e `check:secrets` lo ricevono come `DATABASE_URL`, al posto del canary: una pagina prerenderizzata dal database lo legge davvero, e `check secrets` cerca il valore che la build ha ricevuto. Gli altri passi non lo vedono, e senza `database-url` i comandi ricevono l'ambiente del job com'è. Le PR di Dependabot e quelle da un fork non ricevono `NEON_API_KEY`: il branch non nasce, `database-url` arriva vuoto, e con `migrate` l'action non migra, lo dice con un `::notice::` e prosegue. I test di integrazione si saltano da soli, e la build riceve il canary, quindi una pagina prerenderizzata dal database non ha un database da leggere, e la build si ferma.
+
+**Le migrazioni al deploy.** Con un database, anche `actions/deploy` riceve lo script delle migrazioni, con l'indirizzo di produzione:
+
+```yaml
+      - uses: Elia97/officina/actions/deploy@vX.Y.Z
+        with:
+          migrate: db:migrate
+          database-url: ${{ secrets.PRODUCTION_DATABASE_URL }}
+```
+
+Dopo `vercel pull` e `check:placeholders --env`, subito prima di `vercel build`, l'action lancia `officina migrate --production --script <migrate>`, che dà l'indirizzo allo script sotto `database.migrationUrlKey`, e solo sotto quella. `PRODUCTION_DATABASE_URL` è un segreto dell'environment `production` del repository, che il job di deploy dichiara: lo leggono solo i job di quell'environment, e solo dai ref che le sue regole ammettono, da restringere a `main` e ai tag di release, perché senza regole lo legge un job su qualunque branch. È l'indirizzo diretto al database, senza pooler, come `DATABASE_URL_UNPOOLED` su Neon. Senza `database-url` il passo delle migrazioni si ferma, e il deploy con lui. `doctor` avvisa anche quando il deploy riceve `TEST_DATABASE_URL`, o la CI `PRODUCTION_DATABASE_URL`: le migrazioni andrebbero sul database sbagliato, uscendo 0. Il runner maschera il segreto intero, ma non la password da sola: il comando registra con `::add-mask::` l'indirizzo e la sua password, com'è e decodificata, su stdout e su stderr, e lancia lo script quando le maschere sono scritte.
+
+**Il segreto delle migrazioni.** Su Vercel la chiave delle migrazioni non serve, e se l'applicazione la usa a runtime può restare Secret. Una risorsa del Marketplace impostata su «Production only», che protegge le sue credenziali come Secret, non ferma più le migrazioni. Rende però Secret anche `DATABASE_URL`, e una build che legge il database la riceve come `[SENSITIVE]` e si ferma, a migrazioni già applicate. Il prezzo è un secondo posto da tenere allineato: quando cambia l'indirizzo, che sia la password, l'host o il database, il segreto va aggiornato anche su GitHub. Con una password vecchia il deploy si ferma al passo delle migrazioni. Se invece il database vecchio risponde ancora, le migrazioni vanno lì, e il deploy non se ne accorge.
+
+**Migrazioni compatibili con la produzione.** Le migrazioni si applicano prima della build: se poi la build o il deploy falliscono, la produzione resta sul codice di prima con lo schema nuovo, e lo schema non torna indietro né promuovendo il deployment precedente, quando fallisce lo smoke, né deployando un tag più vecchio. Ogni migrazione deve quindi reggere il codice in produzione, e additiva non basta: lo rompono, senza togliere niente, un `NOT NULL` senza default, un `UNIQUE`, un `CHECK` o una chiave esterna nuovi su dati che quel codice scrive, come un cambio di tipo o un vincolo più stretto. Ciò che toglie arriva dopo: una colonna si toglie quando nessun deployment che si potrebbe promuovere la legge più, e una rinomina passa da una colonna nuova, che il codice scrive insieme alla vecchia, prima di togliere la vecchia in una release successiva.
+
+**Un tempo massimo.** Il passo delle migrazioni non ne ha uno, e il passo di una composite action non accetta `timeout-minutes`. Una migrazione che aspetta un lock blocca, finché non lo ottiene, le query di produzione su quella tabella: le migrazioni del progetto chiedono un `lock_timeout`, con `SET lock_timeout` di Postgres in testa al file, e il job di deploy un `timeout-minutes`, come nell'esempio del deploy.
+
 Quello che si scarica al volo è fissato a una versione esatta, in un posto solo: la CLI di Vercel in `actions/deploy/action.yml`, `@lhci/cli` in `src/checks/lighthouse.ts`, `serve` in `src/sh/lhci-local.sh`. Che i primi due siano esatti, uguali ovunque e non indietro di una major su npm lo guarda ogni lunedì `.github/workflows/vercel-cli.yml`, con `officina check vercel-cli`.
 
 Perché le action non restino ferme per sempre, Dependabot di questo repository copre l'ecosistema `github-actions` anche dentro `/actions/*`, dove le action di terze parti sono fissate allo SHA intero con la versione nel commento.
 
 ## doctor
 
-`officina doctor` dice, in qualunque repository, cosa manca perché il progetto prenda tutto da fuori: i punti di aggancio dei generatori, gli ancoraggi delle pagine a sezioni e dei dizionari, gli script, le dipendenze e gli strumenti di `package.json`, i residui di ciò che è uscito (copia del metodo, script, documenti commerciali), i preset, i workflow di GitHub e Dependabot, `officina.config.ts`. Sta dentro `ci`, quindi un progetto allineato non torna indietro senza che il gate lo dica.
+`officina doctor` dice, in qualunque repository, cosa manca perché il progetto prenda tutto da fuori: i punti di aggancio dei generatori, gli ancoraggi delle pagine a sezioni e dei dizionari, gli script, le dipendenze e gli strumenti di `package.json`, i residui di ciò che è uscito (copia del metodo, script, documenti commerciali), i preset, i workflow di GitHub e Dependabot, `officina.config.ts` e, con un database o l'autenticazione, ciò che li rende sicuri. Sta dentro `ci`, quindi un progetto allineato non torna indietro senza che il gate lo dica.
 
 Di `.github/dependabot.yml` guarda la **forma**, non la presenza delle chiavi: lo legge come YAML e pretende che le chiavi del gruppo stiano sul gruppo — Dependabot rifiuta l'intero file se `commit-message` o `open-pull-requests-limit` stanno su una voce che dichiara `multi-ecosystem-group` — e che ogni ecosistema del gruppo abbia una seconda voce per il resto. Senza quella, `patterns` restringe l'intera voce e tutto il resto smette di aggiornarsi senza che niente diventi rosso. Le action le cerca con il nome che dà loro Dependabot, quello del repository senza la sottocartella: `Elia97/officina`. `Elia97/officina/*` non corrisponde a nessuna dipendenza, in `patterns` come in `ignore` o in `exclude-patterns`, e `doctor` lo segnala ovunque compaia.
 
@@ -177,7 +251,9 @@ Le altre sezioni misurano che il progetto e il pacchetto si muovano insieme:
 - **una PR sola**: il `.github/dependabot.yml` del progetto deve avere un gruppo `multi-ecosystem-groups` che prende `@elia97/officina` da npm e `Elia97/officina` da `github-actions`. Senza, Dependabot ne apre due e il controllo qui sopra le boccia entrambe;
 - **gli strumenti che preset e action danno per scontati**: `@biomejs/biome`, `lefthook`, `@commitlint/cli`, `@commitlint/config-conventional` e `fallow` fra le `devDependencies`, con la versione di Biome dentro l'intervallo che il preset dichiara di reggere.
 
-`package.json`, `.claude/settings.json`, `biome.json` e `.mcp.json` si leggono come JSON, non cercandoci dentro delle stringhe: `"hooks"` in un valore qualunque non è un blocco `hooks`. I workflow restano una ricerca testuale — non c'è un parser YAML nel pacchetto — ma una riga commentata non soddisfa nessun controllo.
+Con `features.database` o `features.auth` accese c'è una sezione in più, «database e autenticazione», che chiede ciò che rende sicuro un progetto con dati e utenti. Con il database: gli script `db:generate` e `db:migrate`, `drizzle.config.ts`, gli input `migrate` e `database-url` di `actions/ci` in `ci.yml` e di `actions/deploy` in `deploy.yml`. Per ogni feature accesa, la sua chiave in `env.schema`, `DATABASE_URL` o `BETTER_AUTH_SECRET`, con `context: 'server'` e `access: 'secret'`: una variabile pubblica Astro la scrive nel codice della build. Lo schema si legge dal sorgente di `astro.config.mjs`, senza eseguirlo, quindi una chiave conta se è scritta lì con `context` e `access` per esteso.
+
+`package.json`, `.claude/settings.json`, `biome.json` e `.mcp.json` si leggono come JSON, non cercandoci dentro delle stringhe: `"hooks"` in un valore qualunque non è un blocco `hooks`. Nei workflow i riferimenti alle action si cercano nel testo, perché la versione di uno SHA sta nel commento, e una riga commentata non soddisfa nessun controllo; gli input che un passo dà a un'action si leggono come YAML.
 
 **Un requisito nuovo nasce come avviso.** Quando `doctor` impara a chiedere una cosa nuova, la mancanza è un `warning` nella versione che la introduce e diventa un `error` dalla successiva. `doctor` gira dentro `pnpm run ci` senza `--strict`, quindi la PR di Dependabot che porta la versione nuova passa, e il progetto ha una versione di tempo per adeguarsi. L'avviso serve a far passare quella PR, e dove non può passare comunque il requisito nasce come errore: con il filtro `Elia97/officina/*` l'aggiornamento arriva diviso in due PR, e nessuna delle due passa il controllo sulla stessa versione.
 
@@ -229,4 +305,4 @@ I test dei generatori girano sui punti di aggancio del progetto di prova, copiat
 
 ## Cosa arriverà
 
-I preset di `ecommerce` e `monorepo`.
+I preset di `monorepo`.

package/dist/bin.js

@@ -8,9 +8,11 @@ export const CHECKS = {
     comments: () => import('./checks/comments.js'),
     language: () => import('./checks/language.js'),
     lighthouse: () => import('./checks/lighthouse.js'),
+    links: () => import('./checks/links.js'),
     placeholders: () => import('./checks/placeholders.js'),
     roadmap: () => import('./checks/roadmap.js'),
     routes: () => import('./checks/routes.js'),
+    secrets: () => import('./checks/secrets.js'),
     smoke: () => import('./checks/smoke.js'),
     'vercel-cli': () => import('./checks/vercel-cli.js'),
 };
@@ -19,9 +21,10 @@ const USAGE = `Uso:
   officina gen [generatore]         section, page, component, collection, più quelli del progetto
   officina gen icons                le icone del manifest da public/favicon.svg
   officina doctor                   cosa manca al progetto perché i generatori funzionino
+  officina migrate --script <nome>  le migrazioni sotto database.migrationUrlKey: da TEST_DATABASE_URL, o con --production da PRODUCTION_DATABASE_URL
 
 Opzioni dei gate sui sorgenti: --diff, --base <ref>, --head <ref>, --strict, --format text|github
-bundle legge dist/client; smoke [url] e analytics [GTM-…] vanno in rete; lighthouse [--local]
+bundle, links e secrets leggono dist/client; smoke [url] e analytics [GTM-…] vanno in rete; lighthouse [--local]
 I valori del progetto (URL, budget, header, controlli propri) stanno in officina.config.ts
 `;
 // Ogni gruppo dice quale modulo carica e quali argomenti gli passa.
@@ -31,6 +34,7 @@ const GROUPS = {
         ? { load: () => import('./gen/icons.js'), args: args.slice(1) }
         : { load: () => import('./gen/run.js'), args },
     doctor: (args) => ({ load: () => import('./checks/doctor.js'), args }),
+    migrate: (args) => ({ load: () => import('./checks/migrate.js'), args }),
 };
 export async function run(argv) {
     const [group = '', ...rest] = argv;

package/dist/checks/bundle.js

@@ -9,7 +9,7 @@ import { measureCss, routeCount } from '../lib/bundle-css.js';
 import { readSsr } from '../lib/bundle-ssr.js';
 import { missingInput } from '../lib/cli.js';
 import { loadConfig } from '../lib/config.js';
-import { expectedRoutes, filesWithExtension, missingRouteFailures, readPageFiles, routeOf, } from '../lib/routes.js';
+import { disabledRouteFailures, expectedRoutes, filesWithExtension, missingRouteFailures, readPageFiles, routeOf, } from '../lib/routes.js';
 const DIST = 'dist/client';
 const ASSETS = join(DIST, '_astro');
 const PAGES = 'src/pages';
@@ -98,8 +98,15 @@ function printSsrNote(expected, ssr) {
     for (const file of expected.ssr)
         console.log(`      - ${file}`);
 }
+function printDisabled({ disabled }) {
+    if (disabled.length === 0)
+        return;
+    console.log('\nSPENTE  da `routes.disabled`, nessuna pagina attesa:');
+    for (const { label, file } of disabled)
+        console.log(`      - ${label} (${file})`);
+}
 export async function main() {
-    const { bundle = {} } = await loadConfig(process.cwd());
+    const { bundle = {}, routes: { disabled } = {} } = await loadConfig(process.cwd());
     if (missingInput(ASSETS, 'è la build da misurare: prima `pnpm build`'))
         return 1;
     if (missingInput(PAGES, 'le rotte attese si derivano da lì'))
@@ -109,14 +116,17 @@ export async function main() {
     const ssr = readSsr(html.length > 0);
     const routes = [...html, ...ssr.pages];
     const pages = measurePages(routes, readChunks(), bundle.budgets ?? []);
-    const expected = expectedRoutes(readPageFiles(PAGES), PAGES);
-    const measured = pages.map((page) => page.route);
-    const failures = ssr.comparesExpectedRoutes ? missingRouteFailures(expected, measured, DIST) : [];
+    const expected = expectedRoutes(readPageFiles(PAGES), PAGES, disabled);
+    const emitted = { html: html.map((page) => page.route), ssr: ssr.pages.map((page) => page.route) };
+    const failures = ssr.comparesExpectedRoutes
+        ? [...missingRouteFailures(expected, emitted, DIST), ...disabledRouteFailures(expected, emitted)]
+        : [];
     failures.push(...ssr.failures, ...unknownChunkFailures(pages), ...overBudgetFailures(pages));
     const width = Math.max('ROTTA'.length, ...pages.map((p) => p.route.length));
     printPages(pages, width);
     failures.push(...checkCss(routes, cssMaxGzip, width));
     printSsrNote(expected, ssr);
+    printDisabled(expected);
     if (failures.length > 0) {
         console.error(`\n✗ Budget di bundle:\n${failures.map((f) => `  - ${f}`).join('\n')}\n`);
         return 1;

package/dist/checks/doctor.js

@@ -3,15 +3,16 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { PROJECT_GENERATORS } from '../gen/plopfile.mjs';
-import { dependencyGaps, leftoverGaps, presetGaps, scriptGaps, } from '../lib/alignment.js';
+import { dependencyGaps, leftoverGaps, presetGaps, readManifest, scriptGaps, } from '../lib/alignment.js';
 import { anchorGaps } from '../lib/anchors.js';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
-import { findConfigFile, generatorsSetting, loadConfig, } from '../lib/config.js';
+import { featuresOffByChoice, featuresOn, findConfigFile, generatorsSetting, loadConfig, } from '../lib/config.js';
 import { configGaps } from '../lib/config-gaps.js';
 import { contractGaps } from '../lib/contract.js';
+import { databaseAuthGaps } from '../lib/database-auth.js';
 import { dependabotGaps } from '../lib/dependabot.js';
 import { trackedAndUntracked } from '../lib/git.js';
-import { expectedRoutes, missingRepresentatives, readPageFiles } from '../lib/routes.js';
+import { expectedRoutes, missingRepresentatives, readPageFiles, unknownDisabled } from '../lib/routes.js';
 import { toolingGaps } from '../lib/tooling.js';
 import { packageVersion } from '../lib/versions.js';
 import { workflowGaps } from '../lib/workflows.js';
@@ -22,14 +23,6 @@ function projectFiles(root) {
         read: (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined),
     };
 }
-function readManifest(files) {
-    try {
-        return JSON.parse(files.read('package.json') ?? '{}');
-    }
-    catch {
-        return {};
-    }
-}
 async function loadedConfig(root) {
     if (findConfigFile(root) === undefined)
         return undefined;
@@ -64,11 +57,31 @@ function generatorSections(root, setting) {
         { title: ANCHORS, off },
     ];
 }
-function orphanPatterns(root, config) {
+function routeGaps(root, config) {
+    if (config === undefined || config instanceof Error)
+        return { disabled: [] };
     const pages = join(root, PAGES);
-    if (!existsSync(pages) || config === undefined || config instanceof Error)
-        return [];
-    return missingRepresentatives(expectedRoutes(readPageFiles(pages), pages), config.routes?.representatives);
+    const { representatives, disabled: declared } = config.routes ?? {};
+    const expected = expectedRoutes(existsSync(pages) ? readPageFiles(pages) : [], pages, declared);
+    return {
+        missingRepresentatives: missingRepresentatives(expected, representatives),
+        unknownDisabled: unknownDisabled(expected, declared),
+        disabled: expected.disabled.map(({ label }) => label),
+    };
+}
+function configSection(root, config) {
+    const { disabled, ...gaps } = routeGaps(root, config);
+    const notes = disabled.length === 0 ? [] : [`spente da \`routes.disabled\`: ${disabled.join(', ')}`];
+    return { title: 'officina.config.ts', gaps: configGaps(config, gaps), notes };
+}
+const DATABASE_AUTH = 'database e autenticazione';
+function databaseAuthSections(files, config, manifest) {
+    const on = featuresOn(config, manifest);
+    const off = featuresOffByChoice(config, manifest).map((name) => `\`features.${name}: false\``);
+    if (on.length === 0)
+        return off.length === 0 ? [] : [{ title: DATABASE_AUTH, off: off.join(' e ') }];
+    const notes = off.map((setting) => `spenta da ${setting}`);
+    return [{ title: DATABASE_AUTH, gaps: databaseAuthGaps(files, manifest, on), notes }];
 }
 export async function main() {
     const root = process.cwd();
@@ -88,7 +101,8 @@ export async function main() {
             title: 'workflow di GitHub e Dependabot',
             gaps: [...workflowGaps(files, version), ...dependabotGaps(files)],
         },
-        { title: 'officina.config.ts', gaps: configGaps(config, orphanPatterns(root, config)) },
+        configSection(root, config),
+        ...databaseAuthSections(files, usable(config), manifest),
     ];
     console.log(`\nofficina doctor ${version} — cosa manca al progetto per prendere tutto da fuori\n`);
     const findings = [];
@@ -101,6 +115,8 @@ export async function main() {
         console.log(gaps.length === 0 ? `  ✓ ${title}` : `  ${title}: ${gaps.length}`);
         const sectionFindings = gaps.map((gap) => ({ ...gap, severity: gap.severity ?? 'error' }));
         printFindings(sectionFindings, cliOptions([]).format);
+        for (const note of section.notes ?? [])
+            console.log(`    · ${note}`);
         findings.push(...sectionFindings);
     }
     console.log(findings.length === 0

package/dist/checks/lighthouse.js

@@ -25,13 +25,16 @@ async function resolveConfig(url) {
     if (missingInput(PAGES_DIR, 'le rotte da visitare si derivano da lì'))
         return null;
     const rc = JSON.parse(readFileSync(RC_FILE, 'utf8'));
-    const routes = auditRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR), configured.representatives);
+    const expected = expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR, configured.disabled);
+    const routes = auditRoutes(expected, configured.representatives);
     const env = url === undefined ? process.env : { ...process.env, LH_BASE_URL: url };
     const resolved = lighthouseConfig(rc, routes, env);
     const where = url === undefined ? '' : ` su ${url}`;
     console.log(`\nLighthouse CI — ${routes.length} rotta/e derivate da ${PAGES_DIR}${where}\n`);
     for (const page of resolved.ci.collect.url ?? [])
         console.log(`  ${page}`);
+    for (const { label } of expected.disabled)
+        console.log(`  ${label} — spenta da \`routes.disabled\`, non misurata`);
     console.log();
     return resolved;
 }

package/dist/checks/links.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<number>;

package/dist/checks/links.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import process from 'node:process';
+import { readServerFiles } from '../lib/bundle-ssr.js';
+import { missingInput } from '../lib/cli.js';
+import { isRequired, loadConfig } from '../lib/config.js';
+import { brokenLines, htmlLinks, linkReport, servedPaths, siteOrigin } from '../lib/links.js';
+import { expectedRoutes, filesWithExtension, pageRouteOf, readPageFiles, routeOf, routePattern } from '../lib/routes.js';
+import { onDemandPatterns } from '../lib/vercel-build.js';
+const DIST = 'dist/client';
+const PAGES = 'src/pages';
+const SERVER_OUTPUT = 'dist/server';
+const FROM_SOURCE = 'valgono le pagine `.astro` con `prerender = false`';
+const servedPath = (file) => `/${relative(DIST, file).split(sep).join('/')}`;
+function onDemand() {
+    const files = readServerFiles();
+    const fromBuild = files.length === 0 ? null : onDemandPatterns(files);
+    if (fromBuild !== null)
+        return { patterns: fromBuild };
+    const ssr = existsSync(PAGES) ? expectedRoutes(readPageFiles(PAGES), PAGES).ssr : [];
+    const patterns = ssr.map((file) => routePattern(pageRouteOf(file, PAGES)));
+    if (files.length > 0)
+        return { patterns, note: `il manifest della build Vercel non si riconosce: ${FROM_SOURCE}` };
+    if (existsSync(SERVER_OUTPUT))
+        return { patterns, note: `build SSR senza l'adapter Vercel: ${FROM_SOURCE}` };
+    return { patterns };
+}
+function printReport(report, pages, note) {
+    console.log(`\ncheck:links — ${report.internal} link interni su ${pages} pagine di ${DIST}\n`);
+    const { external, scheme, anchor } = report.outside;
+    console.log(`Restano fuori: ${external} link esterni, ${scheme} con un altro schema (mailto:, tel:, …), ${anchor} ancore, di cui l'id non si verifica.`);
+    if (report.onDemand > 0) {
+        console.log(`${report.onDemand} link portano a una rotta resa a richiesta: che la pagina esista lo sa solo il server.`);
+    }
+    if (note !== undefined)
+        console.log(`\nNOTA  ${note}`);
+}
+export async function main() {
+    const config = await loadConfig(process.cwd());
+    if (!isRequired(config, 'links')) {
+        console.log('\ncheck:links — spento da `features.links: false`\n');
+        return 0;
+    }
+    if (missingInput(DIST, 'è la build di cui si controllano i link: prima `pnpm build`'))
+        return 1;
+    const files = filesWithExtension(DIST, '').map(servedPath);
+    const html = files.filter((file) => file.endsWith('.html'));
+    if (html.length === 0) {
+        console.error(`\n✗ ${DIST} non contiene nessun .html: senza pagine il controllo dei link non afferma niente.\n`);
+        return 1;
+    }
+    const pages = html.map((file) => ({
+        route: routeOf(file, ''),
+        hrefs: htmlLinks(readFileSync(join(DIST, file), 'utf8')),
+    }));
+    const { patterns, note } = onDemand();
+    const report = linkReport(pages, siteOrigin(config.siteUrl), servedPaths(files), patterns);
+    printReport(report, pages.length, note);
+    if (report.broken.length > 0) {
+        const lines = brokenLines(report).map((line) => `  - ${line}`);
+        console.error(`\n✗ Link interni rotti:\n${lines.join('\n')}\n`);
+        return 1;
+    }
+    console.log('\n✓ Ogni link interno porta a qualcosa che la build serve.\n');
+    return 0;
+}
+if (import.meta.main)
+    process.exit(await main());

package/dist/checks/migrate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(args?: string[]): Promise<number>;

package/dist/checks/migrate.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { maskCommand } from '../lib/cli.js';
+import { loadConfig, migrationUrlKey } from '../lib/config.js';
+import { maskedValues, migrationEnv } from '../lib/migrate.js';
+const written = (stream, text) => new Promise((resolve, reject) => {
+    stream.write(text, (error) => (error ? reject(error) : resolve()));
+});
+export async function main(args = process.argv.slice(2)) {
+    const options = { script: { type: 'string' }, production: { type: 'boolean' } };
+    const { script, production } = parseArgs({ args, options }).values;
+    if (!script) {
+        console.error('\n✗ manca `--script`: il nome dello script delle migrazioni, per esempio `db:migrate`.\n');
+        return 1;
+    }
+    const key = migrationUrlKey(await loadConfig(process.cwd()));
+    const migration = migrationEnv(process.env, key, production ? 'production' : 'test');
+    if ('error' in migration) {
+        console.error(`\n✗ ${migration.error}.\n`);
+        return 1;
+    }
+    if (process.env.GITHUB_ACTIONS) {
+        // Su una pipe piena libuv scrive il resto solo dopo `spawnSync`; il runner legge stderr prima di stdout
+        // in ogni lotto di righe.
+        const masks = `${maskedValues(migration.url).map(maskCommand).join('\n')}\n`;
+        await Promise.all([written(process.stdout, masks), written(process.stderr, masks)]);
+    }
+    const where = production ? 'in produzione' : 'sul branch di test';
+    console.log(`\nmigrate — \`pnpm run ${script}\` ${where}, con l'indirizzo in \`${key}\`\n`);
+    const { status, signal, error } = spawnSync('pnpm', ['run', script], { stdio: 'inherit', env: migration.env });
+    if (error !== undefined) {
+        console.error(`\n✗ pnpm non parte: ${error.message}.\n`);
+        return 1;
+    }
+    if (signal !== null) {
+        console.error(`\n✗ \`pnpm run ${script}\` si è fermato per ${signal}.\n`);
+        return 1;
+    }
+    return status ?? 1;
+}
+if (import.meta.main)
+    process.exit(await main());

package/dist/checks/placeholders.js

@@ -2,9 +2,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import process from 'node:process';
 import { parseArgs } from 'node:util';
-import { contactEnvKeys, envFindings, outputFindings, placeholderSources, sourceFindings, } from '../lib/check-placeholders.js';
+import { readManifest } from '../lib/alignment.js';
+import { envFindings, outputFindings, placeholderSources, requiredEnvKeys, sourceFindings, } from '../lib/check-placeholders.js';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
-import { loadConfig } from '../lib/config.js';
+import { featuresOn, loadConfig } from '../lib/config.js';
 const MISSING_SOURCE = 'sorgente assente: `placeholders.sources` in officina.config.ts dice quali file guardare';
 function sourceScan(paths) {
     return paths.flatMap((path) => {
@@ -23,21 +24,29 @@ function outputScan(dir) {
         return [{ path: dir, message: 'cartella della build assente: la scrive vercel build', severity: 'error' }];
     return outputFindings(dir);
 }
+const projectFile = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : undefined);
+const ENV_ADVICE = 'Da impostare su Vercel, fra le variabili di produzione, prima del deploy: quali pretendere lo dice `placeholders.contactEnvKeys` in officina.config.ts';
+function envAdvice(on) {
+    if (on.length === 0)
+        return ENV_ADVICE;
+    return `${ENV_ADVICE}, più le chiavi che pretendono ${on.map((name) => `\`features.${name}\``).join(' e ')}`;
+}
 function scan(env, output, config) {
     if (output !== undefined) {
         return {
             scope: `build in ${output}`,
             findings: outputScan(output),
-            clean: 'Nessuna variabile Sensitive entrata nella build.',
-            advice: 'Una variabile che la build legge non può essere Sensitive su Vercel: portala a Encrypted, o leggila a runtime',
+            clean: 'Nessuna variabile Secret entrata nella build.',
+            advice: 'Una variabile che la build legge non può essere Secret su Vercel: va tolta e riaggiunta come Config, o letta a runtime',
         };
     }
     if (env !== undefined) {
+        const manifest = readManifest({ read: projectFile });
         return {
             scope: `ambiente in ${env}`,
-            findings: envScan(env, contactEnvKeys(config)),
+            findings: envScan(env, requiredEnvKeys(config, manifest)),
             clean: 'Nessun segnaposto del template.',
-            advice: 'Da impostare su Vercel, fra le variabili di produzione, prima del deploy: quali pretendere lo dice `placeholders.contactEnvKeys` in officina.config.ts',
+            advice: envAdvice(featuresOn(config, manifest)),
         };
     }
     const paths = placeholderSources(config);

package/dist/checks/secrets.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(args?: string[]): number;