@elia97/officina 0.14.0 → 0.15.0

package/README.md

@@ -76,6 +76,8 @@ 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.
 
+**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.
 
@@ -285,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/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);

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/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.14.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",