@elia97/officina 0.13.0 → 0.15.0

package/README.md

@@ -76,7 +76,9 @@ Per Lighthouse un sito SSR si misura con `check lighthouse <url>`, sulla produzi
 
 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 e nella 0.13.0 un'anomalia è un avviso, che lo smoke stampa con `·` senza fallire; dalla 0.14.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.
+**Prima del dominio.** Un sito può andare in produzione sull'indirizzo di Vercel prima che il DNS punti a Vercel, per esempio per formare sul sito vero chi lo gestirà. Finché il dominio di `siteUrl` non serve la produzione, `smoke.url` in `officina.config.ts` dice dove la serve: l'origine di produzione che Vercel dà al progetto, come `https://<progetto>.vercel.app`, senza percorso né query. Lo smoke senza argomenti prova quella al posto di `siteUrl`, che resta obbligatorio come host canonico, e l'intestazione dell'uscita lo ricorda; così fa anche il deploy, che lancia lo smoke senza indirizzo. Un indirizzo passato a mano vince su `smoke.url`. Su un indirizzo `*.vercel.app` che non è `siteUrl` il controllo del noindex si rovescia: la regola `has: host` di `vercel.json` mette `X-Robots-Tag: noindex` su ogni host di Vercel, quindi lì il noindex deve esserci, per tutti i motori, e un indirizzo di Vercel indicizzabile è il guasto. Vale anche per un indirizzo passato a mano, e un progetto il cui `vercel.json` non ha quella regola lì fallisce. Il controllo dell'host canonico si salta, come per ogni URL di base che non è `siteUrl`. L'URL che stampa `vercel deploy` non si usa: è quello del singolo deployment, che la Standard Protection di Vercel protegge, e lo smoke riceverebbe 401 su ogni pagina, mentre il dominio di produzione resta pubblico. Con il dominio la voce esce, e lo smoke torna sull'apice.
+
+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. Un'anomalia fa fallire lo smoke. 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.
 
@@ -109,7 +111,7 @@ La radice del pacchetto esporta `defineConfig` e i tipi; i pezzi del motore stan
 | `@elia97/officina/bundle` | `CSS_BUDGET_GZIP` |
 | `@elia97/officina/icons` | `ICON_SPECS` |
 
-`siteUrl` serve a `check smoke` e `icons.background` a `gen icons`. I budget del progetto vengono prima del default di 20 KB, nell'ordine in cui sono scritti; `smoke.checks` sostituisce la lista del pacchetto, quindi chi ne toglie un controllo la ricompone da `DEFAULT_CHECKS`; `smoke.securityHeaders` e `smoke.nonHtmlRoutes` sostituiscono `SECURITY_HEADERS` e `NON_HTML_ROUTES`.
+`siteUrl` serve a `check smoke` e `icons.background` a `gen icons`. I budget del progetto vengono prima del default di 20 KB, nell'ordine in cui sono scritti; `smoke.checks` sostituisce la lista del pacchetto, quindi chi ne toglie un controllo la ricompone da `DEFAULT_CHECKS`; `smoke.securityHeaders` e `smoke.nonHtmlRoutes` sostituiscono `SECURITY_HEADERS` e `NON_HTML_ROUTES`; `smoke.url` prende il posto di `siteUrl` come indirizzo da provare, finché il dominio non serve la produzione, come in «Prima del dominio».
 
 `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.
 
@@ -152,7 +154,7 @@ 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`, 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/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; se la PR o il push toccano solo documenti, dopo l'install soltanto `check:language`, `check:routes`, `check:roadmap` e `doctor` | 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`, 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` |
@@ -183,6 +185,8 @@ jobs:
 
 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 percorso veloce dei documenti.** Dopo l'install `actions/ci` lancia `officina scope`, che confronta l'`HEAD` del checkout con la base dell'evento: per una PR la sua base, mentre l'`HEAD` è il merge commit di GitHub; per un push il commit `before`. Se ogni file cambiato è un documento, cioè un `.md` alla radice, sotto `docs/`, sotto `.github/` o sotto `.claude/`, l'action lancia soltanto `check:language`, `check:routes`, `check:roadmap` e `doctor`, e salta il resto: `astro sync`, le migrazioni, `pnpm run ci`, la build, `perf:bundle`, `check:links`, `check:secrets` e gli e2e. `doctor` resta perché alcuni Markdown, come gli agenti in `.claude/agents/` o `docs/DECISIONS.md`, sono residui che vieta. Un'immagine o uno snippet in `docs/`, e `src/content/` anche quando è Markdown, fanno il percorso completo. Il job parte comunque, perché `ci` è un check obbligatorio e un `paths-ignore` sulla PR lo lascerebbe appeso. Nel dubbio il percorso è completo: un evento senza base, come il primo push di un branch, un diff che non riesce, nessun file cambiato, un file che non è un documento, che il log del passo nomina, o `officina scope` che fallisce, e allora il passo lo dice con un avviso. Il confronto è fra due alberi e scarica la sola base, senza la storia: il percorso veloce vuol dire che, fuori dai documenti, l'albero da provare è identico a quello della base, e una base andata avanti nel frattempo aggiunge file al diff e riporta il percorso completo. Uno spostamento conta come cancellazione più aggiunta, quindi un file di codice spostato in `docs/` non passa per documento. Su un push il percorso veloce non riprova il codice di `before`, come un `paths-ignore`.
+
 **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.
@@ -217,7 +221,7 @@ I tre segreti sono input obbligatori e l'action li mette nell'`env` dei soli tre
           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`.
+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` fallisce 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.
 
@@ -230,7 +234,7 @@ Prima di `pnpm run ci` l'action lancia `officina migrate --script <migrate>`, ch
           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.
+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` fallisce 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.
 
@@ -283,7 +287,9 @@ I sorgenti sono TypeScript, ma il pacchetto pubblica JavaScript: Node toglie i t
 
 ## Pubblicare
 
-**Una release a settimana**, salvo una rottura che ferma un progetto: le correzioni si accumulano su `main` ed escono insieme. Ogni release è un aggiornamento da portare in ogni progetto e nel template, e il gruppo `officina` di Dependabot lo propone una volta a settimana: rilasciare più spesso non lo fa arrivare prima, moltiplica soltanto le PR da seguire.
+**Finché officina cambia spesso, una release quando una modifica è pronta.** I progetti la ricevono a mano, perché la PR del gruppo `officina` di Dependabot non passa `doctor`: aspettare la settimana rimanderebbe soltanto la correzione che un progetto aspetta.
+
+**Poi una release a settimana**, salvo una rottura che ferma un progetto. Il passaggio si decide, non scatta da solo. Le correzioni si accumuleranno su `main` per uscire insieme: ogni release è un aggiornamento da portare in ogni progetto e nel template, e il gruppo `officina` di Dependabot lo propone una volta a settimana. Rilasciare più spesso non lo fa arrivare prima, moltiplica soltanto le PR da seguire.
 
 ```sh
 npm pkg set version=X.Y.Z

package/dist/bin.js

@@ -22,6 +22,7 @@ const USAGE = `Uso:
   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
+  officina scope                    in actions/ci, docs-only=true se la PR o il push toccano solo documenti
 
 Opzioni dei gate sui sorgenti: --diff, --base <ref>, --head <ref>, --strict, --format text|github
 bundle, links e secrets leggono dist/client; smoke [url] e analytics [GTM-…] vanno in rete; lighthouse [--local]
@@ -35,6 +36,7 @@ const GROUPS = {
         : { load: () => import('./gen/run.js'), args },
     doctor: (args) => ({ load: () => import('./checks/doctor.js'), args }),
     migrate: (args) => ({ load: () => import('./checks/migrate.js'), args }),
+    scope: (args) => ({ load: () => import('./checks/scope.js'), args }),
 };
 export async function run(argv) {
     const [group = '', ...rest] = argv;

package/dist/checks/scope.d.ts

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

package/dist/checks/scope.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// actions/ci/action.yml appende lo stdout a $GITHUB_OUTPUT: lì va solo `docs-only=…`, la ragione va su stderr.
+import process from 'node:process';
+import { ciScope } from '../lib/ci-scope.js';
+import { changedSince, eventBase } from '../lib/git.js';
+export function main() {
+    const { docsOnly, reason } = ciScope(eventBase(), changedSince);
+    console.error(reason);
+    console.log(`docs-only=${docsOnly}`);
+    return 0;
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/smoke.js

@@ -22,6 +22,9 @@ function printResults(results) {
             console.error(`✗ ${check} — ${detail}`);
     }
 }
+const declaredNote = (argument, { siteUrl, smoke }) => argument === undefined && smoke?.url !== undefined
+    ? `\nda smoke.url, al posto di ${siteUrl}: con il dominio la voce esce`
+    : '';
 const disabledResults = ({ disabled }) => disabled.map(({ label }) => ({ check: `pagina ${label}`, status: 'skip', detail: 'spenta da `routes.disabled`' }));
 function printFailures(failures, database) {
     console.error(`\n✗ ${failures.length} controllo/i falliti:`);
@@ -37,7 +40,8 @@ function printFailures(failures, database) {
 export async function main(args = []) {
     const config = await loadConfig(process.cwd());
     const { siteUrl, smoke = {}, routes = {} } = config;
-    const [url] = args;
+    const [argument] = args;
+    const url = argument ?? smoke.url;
     if (siteUrl === undefined) {
         console.error('\n✗ officina.config.ts non dichiara siteUrl: il controllo dell’host canonico non ha con cosa confrontarsi.\n');
         return 1;
@@ -46,7 +50,6 @@ export async function main(args = []) {
         console.error('\n✗ siteUrl è ancora il segnaposto del template: passa un URL, pnpm smoke:prod https://…\n');
         return 1;
     }
-    // L'apice, non l'URL *.vercel.app che stampa `vercel deploy`: lì la regola `has: host` di vercel.json mette noindex.
     const baseUrl = (url ?? siteUrl).replace(/\/+$/, '');
     const context = {
         get: (target) => fetch(target, { redirect: 'manual' }),
@@ -59,7 +62,7 @@ export async function main(args = []) {
         return 1;
     const expected = expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR, routes.disabled);
     const pages = smokeRoutes(expected, smoke.nonHtmlRoutes, routes.representatives);
-    console.log(`\nSmoke di produzione — ${baseUrl}\n`);
+    console.log(`\nSmoke di produzione — ${baseUrl}${declaredNote(argument, config)}\n`);
     await waitForAlias(context, (ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const onDemand = onDemandPages(expected, PAGES_DIR, routes.representatives);
     const results = await runChecks({ ...context, onDemand }, pages, smoke.checks);
@@ -69,10 +72,6 @@ export async function main(args = []) {
         printFailures(failures, isOn(config, readManifest({ read: projectFile }), 'database'));
         return 1;
     }
-    const warnings = results.filter(({ status }) => status === 'warn').length;
-    // TODO: dalla 0.14.0 le anomalie a richiesta sono `fail` (smoke-on-demand.ts): togli il log degli avvisi qui sotto.
-    if (warnings > 0)
-        console.log(`\n· ${warnings} avviso/i: dalla 0.14.0 fanno fallire lo smoke.`);
     console.log(`\n✓ Tutti i controlli passati su ${baseUrl}.\n`);
     return 0;
 }

package/dist/lib/alignment.js

@@ -28,17 +28,14 @@ export const CI_STEPS = [
     'doctor',
 ];
 const MANIFEST = 'package.json';
-// TODO: dalla 0.14.0 `check:secrets` è un errore di doctor: toglilo da NEW_SCRIPTS.
-const NEW_SCRIPTS = new Set(['check:secrets']);
 export function scriptGaps({ scripts = {} }) {
     const gaps = [];
     for (const [name, expected] of Object.entries(EXPECTED_SCRIPTS)) {
         const actual = scripts[name];
-        const severity = NEW_SCRIPTS.has(name) ? { severity: 'warning' } : {};
         if (actual === undefined)
-            gaps.push({ path: MANIFEST, message: `script \`${name}\` assente: atteso \`${expected}\``, ...severity });
+            gaps.push({ path: MANIFEST, message: `script \`${name}\` assente: atteso \`${expected}\`` });
         else if (!actual.startsWith(expected))
-            gaps.push({ path: MANIFEST, message: `script \`${name}\` è \`${actual}\`: atteso \`${expected}\``, ...severity });
+            gaps.push({ path: MANIFEST, message: `script \`${name}\` è \`${actual}\`: atteso \`${expected}\`` });
     }
     const ci = scripts.ci ?? '';
     for (const step of CI_STEPS) {

package/dist/lib/ci-scope.d.ts

@@ -0,0 +1,6 @@
+export type CiScope = {
+    docsOnly: boolean;
+    reason: string;
+};
+export declare const isDocument: (path: string) => boolean;
+export declare function ciScope(base: string | undefined, changed: (base: string) => string[]): CiScope;

package/dist/lib/ci-scope.js

@@ -0,0 +1,20 @@
+const DOCUMENTS = [/^[^/]+\.md$/, /^(?:docs|\.github|\.claude)\/.+\.md$/];
+export const isDocument = (path) => DOCUMENTS.some((pattern) => pattern.test(path));
+const fullRun = (reason) => ({ docsOnly: false, reason: `percorso completo: ${reason}` });
+export function ciScope(base, changed) {
+    if (base === undefined)
+        return fullRun("l'evento non ha una base con cui confrontarsi");
+    let paths;
+    try {
+        paths = changed(base);
+    }
+    catch (error) {
+        return fullRun(`il diff da ${base} non è riuscito: ${error.message}`);
+    }
+    if (paths.length === 0)
+        return fullRun(`nessun file cambiato da ${base}`);
+    const code = paths.find((path) => !isDocument(path));
+    if (code !== undefined)
+        return fullRun(`${code} non è un documento`);
+    return { docsOnly: true, reason: `percorso veloce: solo documenti (${paths.length} file)` };
+}

package/dist/lib/config.d.ts

@@ -6,7 +6,7 @@ import type { SmokeCheck } from './smoke-production.ts';
 export type FeatureSetting = 'required' | false;
 export type GeneratorsSetting = FeatureSetting | 'project';
 export interface OfficinaConfig {
-    /** L'apice di produzione, senza barra finale: lo usa `check smoke` quando non riceve un URL. */
+    /** L'apice di produzione, senza barra finale: lo usa `check smoke` quando non riceve un URL e `smoke.url` manca. */
     siteUrl?: string;
     icons?: {
         background: string;
@@ -16,6 +16,8 @@ export interface OfficinaConfig {
         cssMaxGzip?: number;
     };
     smoke?: {
+        /** Origine Vercel della produzione, come `https://<progetto>.vercel.app`: lo smoke senza URL prova questa. */
+        url?: string;
         securityHeaders?: Record<string, string | null>;
         nonHtmlRoutes?: readonly VerifiedRoute[];
         checks?: readonly SmokeCheck[];

package/dist/lib/config.js

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { aFunction, aNumber, anArrayOf, anEnvName, aRecordOf, aShape, aString, aStringOrNull, isRecord, oneOf, } from './validate.js';
+import { aFunction, aNumber, anArrayOf, anEnvName, anHttpOrigin, aRecordOf, aShape, aString, aStringOrNull, isRecord, oneOf, } from './validate.js';
 export const FEATURES = ['analytics', 'roadmap', 'generators', 'botId', 'links'];
 /** Un controllo si spegne solo scrivendolo: il silenzio vale `'required'`. */
 export const isRequired = (config, name) => (config.features?.[name] ?? 'required') === 'required';
@@ -40,6 +40,7 @@ const SHAPE = aShape({
     icons: aShape({ background: aString }),
     bundle: aShape({ budgets: anArrayOf(budget), cssMaxGzip: aNumber }),
     smoke: aShape({
+        url: anHttpOrigin,
         securityHeaders: aRecordOf(aStringOrNull),
         nonHtmlRoutes: anArrayOf(verifiedRoute),
         checks: anArrayOf(aFunction),

package/dist/lib/database-auth.js

@@ -72,10 +72,8 @@ function secretGaps(source, keys) {
         return message === undefined ? [] : [{ path: ASTRO_CONFIG, message }];
     });
 }
-// TODO: dalla 0.14.0 i requisiti del database e dell'autenticazione sono errori di doctor: togli `severity`.
-const asWarning = (gap) => ({ ...gap, severity: 'warning' });
 export function databaseAuthGaps(files, manifest, on) {
     const database = on.includes('database') ? databaseGaps(files, manifest) : [];
     const secrets = secretGaps(files.read(ASTRO_CONFIG), on.map((name) => DEPENDENCY_FEATURES[name].secret));
-    return [...database, ...secrets].map(asWarning);
+    return [...database, ...secrets];
 }

package/dist/lib/git.d.ts

@@ -1,4 +1,6 @@
 export declare const trackedAndUntracked: () => string[];
+export declare const eventBase: () => string | undefined;
+export declare function changedSince(base: string): string[];
 export type DiffScope = {
     base?: string | undefined;
     head?: string | undefined;

package/dist/lib/git.js

@@ -19,14 +19,14 @@ export const trackedAndUntracked = () => [
     ...gitPaths('ls-files', []),
     ...gitPaths('ls-files', ['--others', '--exclude-standard']),
 ];
-function ensureCommit(ref) {
+function ensureCommit(ref, { shallow = false } = {}) {
     const exists = spawnSync('git', ['cat-file', '-e', `${ref}^{commit}`], {
         stdio: 'ignore',
     });
     if (exists.status === 0)
         return;
     // Checkout shallow in CI: la base della PR spesso non c'è in locale.
-    git(['fetch', '--no-tags', 'origin', ref]);
+    git(['fetch', '--no-tags', ...(shallow ? ['--depth=1'] : []), 'origin', ref]);
 }
 function defaultBase() {
     const originHead = git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], {
@@ -42,14 +42,29 @@ function defaultBase() {
     }
     throw new Error('nessuna base trovata: passa --base <ref>');
 }
-// Sulle PR GitHub il diff va fatto tra gli SHA dell'evento, non tra branch locali.
-function pullRequestShas() {
+const eventPayload = (name) => {
     const { GITHUB_EVENT_NAME, GITHUB_EVENT_PATH } = process.env;
-    if (GITHUB_EVENT_NAME !== 'pull_request' || !GITHUB_EVENT_PATH || !existsSync(GITHUB_EVENT_PATH))
+    if (GITHUB_EVENT_NAME !== name || !GITHUB_EVENT_PATH || !existsSync(GITHUB_EVENT_PATH))
         return undefined;
-    const { pull_request: pr } = JSON.parse(readFileSync(GITHUB_EVENT_PATH, 'utf8'));
+    return JSON.parse(readFileSync(GITHUB_EVENT_PATH, 'utf8'));
+};
+// Sulle PR GitHub il diff va fatto tra gli SHA dell'evento, non tra branch locali.
+function pullRequestShas() {
+    const pr = eventPayload('pull_request')?.pull_request;
     return pr?.base?.sha && pr?.head?.sha ? { base: pr.base.sha, head: pr.head.sha } : undefined;
 }
+// Il primo push di un branch porta come `before` uno SHA tutto zeri, che non è un commit.
+function pushBefore() {
+    const before = eventPayload('push')?.before;
+    return typeof before === 'string' && !/^0+$/.test(before) ? before : undefined;
+}
+export const eventBase = () => pullRequestShas()?.base ?? pushBefore();
+export function changedSince(base) {
+    ensureCommit(base, { shallow: true });
+    // Con il rilevamento delle rinomine, attivo di default, `--name-only` elenca solo il percorso nuovo;
+    // `submodule.<nome>.ignore = all` in .gitmodules toglie dal diff anche un sottomodulo aggiornato.
+    return gitPaths('diff', ['--name-only', '--no-renames', '--ignore-submodules=none', base, 'HEAD']);
+}
 export function changedFiles({ base, head }) {
     const pr = base ? undefined : pullRequestShas();
     const from = base ?? pr?.base ?? defaultBase();

package/dist/lib/smoke-on-demand.js

@@ -18,16 +18,15 @@ const attributeValue = (tag, attribute) => {
 };
 const hasCspMeta = (html) => [...html.matchAll(META)].some(([tag]) => attributeValue(tag, HTTP_EQUIV).toLowerCase() === 'content-security-policy' &&
     SCRIPT_SRC.test(attributeValue(tag, CONTENT)));
-// TODO: dalla 0.14.0 un'anomalia di una pagina resa a richiesta fa fallire lo smoke: qui `warn` diventa `fail`.
-const warn = (check, detail) => ({ check, status: 'warn', detail });
+const fail = (check, detail) => ({ check, status: 'fail', detail });
 function redirect(check, response, url) {
     const location = response.headers.get('location');
     if (location === null)
-        return warn(check, `risponde ${response.status} senza location`);
+        return fail(check, `risponde ${response.status} senza location`);
     const target = new URL(location, url);
     const { origin } = new URL(url);
     if (target.origin !== origin)
-        return warn(check, `rimanda a ${target.href}, fuori da ${origin}`);
+        return fail(check, `rimanda a ${target.href}, fuori da ${origin}`);
     return { check, status: 'pass' };
 }
 async function visit({ get, baseUrl }, path) {
@@ -38,17 +37,17 @@ async function visit({ get, baseUrl }, path) {
         if (response.status >= 300 && response.status < 400)
             return redirect(check, response, url);
         if (response.status !== 200) {
-            return warn(check, `atteso 200 o un redirect sulla stessa origine, ricevuto ${response.status}`);
+            return fail(check, `atteso 200 o un redirect sulla stessa origine, ricevuto ${response.status}`);
         }
         const contentType = response.headers.get('content-type') ?? '';
         if (!contentType.includes('text/html'))
-            return warn(check, `atteso un content-type text/html, ricevuto "${contentType}"`);
+            return fail(check, `atteso un content-type text/html, ricevuto "${contentType}"`);
         if (!hasCspMeta((await response.text?.()) ?? ''))
-            return warn(check, 'manca il meta Content-Security-Policy con script-src');
+            return fail(check, 'manca il meta Content-Security-Policy con script-src');
         return { check, status: 'pass' };
     }
     catch (error) {
-        return warn(check, error instanceof Error ? error.message : String(error));
+        return fail(check, error instanceof Error ? error.message : String(error));
     }
 }
 export async function checkOnDemandPages(context) {

package/dist/lib/smoke-production.d.ts

@@ -29,7 +29,7 @@ export declare const BOTID_CHALLENGE = "/149e9513-01fa-4fb0-aad4-566afd725d1b/2d
 /** L'alias di produzione di Vercel impiega un attimo a puntare al deployment appena caricato. */
 export declare function waitForAlias({ get, baseUrl }: SmokeContext, sleep: (ms: number) => Promise<void>, attempts?: number): Promise<void>;
 export declare function checkPages({ get, baseUrl }: SmokeContext, pages: readonly VerifiedRoute[]): Promise<CheckResult[]>;
-export declare function checkSecurityHeaders({ get, baseUrl, securityHeaders }: SmokeContext): Promise<CheckResult[]>;
+export declare function checkSecurityHeaders(context: SmokeContext): Promise<CheckResult[]>;
 export declare function checkBotIdChallenge({ get, baseUrl, botIdRequired }: SmokeContext): Promise<CheckResult[]>;
 /** Il 308 da www all'apice, da vercel.json: dipende dal DNS e dal dominio del progetto Vercel, non dal deployment. */
 export declare function checkCanonicalHost({ get, baseUrl, siteUrl }: SmokeContext): Promise<CheckResult[]>;

package/dist/lib/smoke-production.js

@@ -1,4 +1,5 @@
 import { checkOnDemandPages } from './smoke-on-demand.js';
+import { checkRobotsTag } from './smoke-robots.js';
 const pass = (check) => ({ check, status: 'pass' });
 const fail = (check, detail) => ({ check, status: 'fail', detail });
 const skip = (check, detail) => ({ check, status: 'skip', detail });
@@ -68,7 +69,8 @@ export async function checkPages({ get, baseUrl }, pages) {
     }
     return results;
 }
-export async function checkSecurityHeaders({ get, baseUrl, securityHeaders }) {
+export async function checkSecurityHeaders(context) {
+    const { get, baseUrl, securityHeaders } = context;
     let landing;
     try {
         landing = await landingPage(get, baseUrl);
@@ -87,10 +89,7 @@ export async function checkSecurityHeaders({ get, baseUrl, securityHeaders }) {
             return fail(check, `atteso "${expected}", ricevuto "${value}"`);
         return pass(check);
     });
-    // Il noindex `has: host = *.vercel.app` di vercel.json applicato al dominio vero farebbe sparire il sito da ogni indice.
-    const check = 'nessun x-robots-tag sull’host di produzione';
-    const robots = response.headers.get('x-robots-tag');
-    results.push(robots === null ? pass(check) : fail(check, `presente su ${url}: "${robots}"`));
+    results.push(checkRobotsTag(context, url, response.headers.get('x-robots-tag')));
     return results;
 }
 export async function checkBotIdChallenge({ get, baseUrl, botIdRequired }) {

package/dist/lib/smoke-robots.d.ts

@@ -0,0 +1,4 @@
+import type { CheckResult, SmokeContext } from './smoke-production.ts';
+type Addresses = Pick<SmokeContext, 'baseUrl' | 'siteUrl'>;
+export declare function checkRobotsTag(addresses: Addresses, url: string, robots: string | null): CheckResult;
+export {};

package/dist/lib/smoke-robots.js

@@ -0,0 +1,22 @@
+// La regola `has: host` del vercel.json dei progetti mette noindex su ogni `*.vercel.app`:
+// lì deve esserci, e sul dominio vero toglierebbe il sito dagli indici senza nessun errore.
+const onVercel = ({ baseUrl, siteUrl }) => {
+    const { hostname } = new URL(baseUrl);
+    return hostname !== URL.parse(siteUrl)?.hostname && hostname.endsWith('.vercel.app');
+};
+const OUT_OF_INDEX = new Set(['noindex', 'none']);
+const keepsOutOfIndex = (robots) => robots.split(',').some((directive) => OUT_OF_INDEX.has(directive.trim().toLowerCase()));
+export function checkRobotsTag(addresses, url, robots) {
+    if (!onVercel(addresses)) {
+        const check = 'nessun x-robots-tag sull’host di produzione';
+        if (robots === null)
+            return { check, status: 'pass' };
+        return { check, status: 'fail', detail: `presente su ${url}: "${robots}"` };
+    }
+    const check = 'x-robots-tag noindex sull’indirizzo di Vercel';
+    if (robots === null)
+        return { check, status: 'fail', detail: `assente su ${url}` };
+    if (keepsOutOfIndex(robots))
+        return { check, status: 'pass' };
+    return { check, status: 'fail', detail: `senza noindex su ${url}: "${robots}"` };
+}

package/dist/lib/validate.d.ts

@@ -7,6 +7,7 @@ export declare const aNumber: Check;
 export declare const aFunction: Check;
 export declare const aStringOrNull: Check;
 export declare const anEnvName: Check;
+export declare const anHttpOrigin: Check;
 export declare const anArrayOf: (item: Check) => Check;
 export declare const aRecordOf: (item: Check) => Check;
 export declare const oneOf: (expected: string, allowed: readonly unknown[]) => Check;

package/dist/lib/validate.js

@@ -26,6 +26,15 @@ export const anEnvName = (value, path) => {
         return [];
     return [`${path}: atteso il nome di una variabile d'ambiente, ricevuto ${JSON.stringify(value)}`];
 };
+const HTTP = new Set(['http:', 'https:']);
+export const anHttpOrigin = (value, path) => {
+    if (typeof value !== 'string')
+        return [problem(path, 'una stringa', value)];
+    const url = URL.parse(value);
+    if (url !== null && HTTP.has(url.protocol) && url.href === `${url.origin}/`)
+        return [];
+    return [`${path}: atteso un'origine http o https, senza percorso né query, ricevuto ${JSON.stringify(value)}`];
+};
 export const anArrayOf = (item) => (value, path) => Array.isArray(value)
     ? value.flatMap((entry, index) => item(entry, `${path}[${index}]`))
     : [problem(path, 'un array', value)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elia97/officina",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Gli strumenti dei progetti nati dai template di Elia: gate di qualità, generatori e verifiche di build e di produzione.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "test:pack": "bash scripts/pack-test.sh"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
+    "@biomejs/biome": "2.5.15",
     "@types/node": "^26.5.1",
     "@vitest/coverage-v8": "^4.1.11",
     "fallow": "^3.26.0",