@elia97/officina 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,6 @@ pnpm add -D @elia97/officina
     "check:routes": "officina check routes",
     "check:roadmap": "officina check roadmap",
     "check:placeholders": "officina check placeholders",
-    "check:vercel-cli": "officina check vercel-cli",
     "perf:bundle": "officina check bundle",
     "smoke:prod": "officina check smoke",
     "analytics:verify": "officina check analytics",
@@ -43,9 +42,9 @@ I gate leggono dalla cartella corrente, che deve essere la radice del repository
 |---|---|---|
 | `check bundle` | il JavaScript e il CSS di `dist/client`, gzip, contro un budget per rotta | `src/pages` |
 | `check smoke [url]` | la produzione viva: pagine, 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 di `src/lib/analytics/link-tracking.ts` | — |
+| `check analytics [GTM-…]` | il container GTM pubblico contro gli eventi del modulo di link-tracking del progetto (`analytics.linkTracking`) | — |
 | `check lighthouse [--local]` | Lighthouse CI sul `.lighthouserc.json` del progetto; `--local` fa build, server e Chrome da sé | `src/pages` |
-| `gen icons` | le icone del manifest, disegnate da `public/favicon.svg` | — |
+| `gen icons` | le icone del manifest, disegnate dal favicon SVG in `public/` del progetto | — |
 
 Il motore è uguale per tutti; ciò che cambia da un progetto all'altro sta in un file solo, `officina.config.ts` nella radice:
 
@@ -69,6 +68,58 @@ Ogni voce è facoltativa, tranne `siteUrl` per `check smoke` e `icons.background
 
 `sharp` è una dipendenza facoltativa del progetto, non del pacchetto: serve solo a `gen icons`, che senza lo dice ed esce 1. `ICON_SPECS` si importa senza caricarlo, per il test che confronta le icone con il manifest del sito.
 
+## Preset di configurazione
+
+Le regole che valgono per tutti i progetti stanno nel pacchetto; il progetto estende e tiene solo le proprie eccezioni.
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
+  "extends": ["@elia97/officina/biome"]
+}
+```
+
+```yaml
+# lefthook.yml
+extends:
+  - node_modules/@elia97/officina/presets/lefthook.yml
+```
+
+## Action per i workflow
+
+I passi dei workflow stanno in `actions/` di questo repository, come composite action: girano dentro il job di chi le chiama, quindi il nome del check, l'`environment` e i segreti restano del progetto. Il riferimento va fissato a un tag di versione o a uno SHA, mai a `@main`.
+
+| Action | Passi | Cosa resta nel workflow del progetto |
+|---|---|---|
+| `actions/ci` | checkout, node, install, `pnpm run ci`, build, `perf:bundle`; con `e2e: 'true'` anche Playwright | trigger, permessi, il job `ci` |
+| `actions/review` | `fallow review` sul diff contro il merge-base | il job informativo |
+| `actions/deploy` | risoluzione del tag, gate, `vercel pull`, `build`, `deploy`, smoke; espone `url` | trigger, `environment`, i tre segreti Vercel nell'`env` del job, il job che controlla se i segreti ci sono |
+| `actions/lighthouse` | build equivalente alla produzione e `pnpm run lhci` | trigger, etichetta, `continue-on-error` |
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: ${{ steps.deploy.outputs.url }}
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+    steps:
+      - uses: Elia97/officina/actions/deploy@v0.4.0
+        id: deploy
+        with:
+          ref: ${{ inputs.ref }}
+```
+
+Il pin `vercel@<major>` sta in un posto solo, `actions/deploy/action.yml`: lo guarda ogni lunedì `.github/workflows/vercel-cli.yml` di questo repository, con `officina check vercel-cli actions/deploy/action.yml`.
+
+## doctor
+
+`officina doctor` dice, in qualunque repository, cosa manca perché il progetto prenda tutto da fuori: i punti di aggancio dei generatori, gli script e le dipendenze di `package.json`, i residui di ciò che è uscito (copia del metodo, script, documenti commerciali), i preset, i workflow con il riferimento fissato, `officina.config.ts`. Sta dentro `ci`, quindi un progetto allineato non torna indietro senza che il gate lo dica.
+
 ## Sviluppo
 
 ```sh
@@ -91,7 +142,7 @@ pnpm publish     # prepublishOnly lancia typecheck, test e build
 
 `officina gen` avvolge plop con i generatori e i template del pacchetto, e scrive nel progetto da cui lo lanci: `section`, `page`, `component`, `collection`. `plop` e `ts-morph` sono dipendenze del pacchetto, non del progetto.
 
-I generatori scrivono codice che deve incastrarsi nello scaffold, quindi il progetto deve avere i punti di aggancio che si aspettano: i moduli che il codice generato importa e i file in cui iniettano. L'elenco è `src/lib/contract.ts`, e `officina doctor` dice, in qualunque repository, cosa manca. Finché manca qualcosa il pre-volo del generatore si ferma prima di scrivere un solo file.
+I generatori scrivono codice che deve incastrarsi nello scaffold, quindi il progetto deve avere i punti di aggancio che si aspettano: i moduli che il codice generato importa e i file in cui iniettano. L'elenco è `src/lib/contract.ts`, ed è la prima sezione di `officina doctor`. Finché manca qualcosa il pre-volo del generatore si ferma prima di scrivere un solo file.
 
 Un progetto aggiunge i propri generatori con un file `officina.generators.mjs` nella radice, con la firma di un plopfile: `export default function (plop)`.
 

package/dist/checks/analytics.js

@@ -18,30 +18,30 @@ function reportCoverage(coverage) {
     }
     const missing = coverage.filter(({ covered }) => !covered);
     if (missing.length > 0) {
-        console.error(`\n✗ ${missing.length} event(s) the site pushes and no trigger listens for.`);
+        console.error(`\n✗ ${missing.length} evento/i che il sito emette e nessun trigger ascolta.`);
         return 1;
     }
-    console.log('\n✓ Every event the site pushes has a trigger.');
+    console.log('\n✓ Ogni evento che il sito emette ha un trigger.');
     return 0;
 }
 export async function main(args = []) {
     const { analytics = {} } = await loadConfig(process.cwd());
     const gtmId = resolveGtmId(args);
     if (gtmId === null) {
-        console.log('No GTM container to check: pass one as an argument or set PUBLIC_GTM_ID.');
+        console.log('Nessun container GTM da controllare: passane uno come argomento o imposta PUBLIC_GTM_ID.');
         return 0;
     }
     const response = await fetch(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`, {
         signal: AbortSignal.timeout(TIMEOUT_MS),
     });
     if (!response.ok) {
-        console.error(`✗ container ${gtmId} unreadable: HTTP ${response.status}`);
+        console.error(`✗ container ${gtmId} illeggibile: HTTP ${response.status}`);
         return 1;
     }
     const container = parseContainerData(await response.text());
     const source = readFileSync(analytics.linkTracking ?? LINK_TRACKING, 'utf8');
     const coverage = coverageOf(extractLinkEvents(source), extractTriggers(container));
-    console.log(`\nGTM ${gtmId} — measurement IDs: ${googleTagIds(container).join(', ') || '—'}\n`);
+    console.log(`\nGTM ${gtmId} — ID di misurazione: ${googleTagIds(container).join(', ') || '—'}\n`);
     return reportCoverage(coverage);
 }
 if (import.meta.main)

package/dist/checks/bundle.js

@@ -48,18 +48,18 @@ function overBudgetFailures(pages) {
     });
 }
 function printPages(pages, width) {
-    console.log('\nBundle budget — client JS per route (gzip, static closure)\n');
-    console.log(`${'ROUTE'.padEnd(width)}   ${'STATIC'.padStart(9)}   ${'BUDGET'.padStart(9)}   ${'DEFERRED'.padStart(9)}`);
+    console.log('\nBudget di bundle — JS del client per rotta (gzip, chiusura statica)\n');
+    console.log(`${'ROTTA'.padEnd(width)}   ${'STATICO'.padStart(9)}   ${'BUDGET'.padStart(9)}   ${'DIFFERITO'.padStart(9)}`);
     for (const page of pages) {
         const deferred = page.deferredGzip > 0 ? gz(page.deferredGzip) : '—';
         const line = `${page.route.padEnd(width)}   ${gz(page.gzip).padStart(9)}   ${gz(page.budget.maxGzip).padStart(9)}   ${deferred.padStart(9)}`;
         console.log(page.gzip > page.budget.maxGzip ? `${line}  ✗` : line);
     }
-    console.log('\nDEFERRED = reachable only through `await import()` (loaded after paint, behind a runtime guard).');
+    console.log('\nDIFFERITO = raggiungibile solo da `await import()` (caricato dopo il primo paint, dietro una guardia a runtime).');
 }
 function printStylesheets(stylesheets, cssMaxGzip, failed, width) {
     const worst = heaviestStylesheet(stylesheets);
-    console.log(`\nCSS (render-blocking, heaviest sheet a route links)`);
+    console.log(`\nCSS (blocca il rendering: il foglio più pesante che una rotta collega)`);
     for (const sheet of [...stylesheets].sort((a, b) => b.gzip - a.gzip)) {
         const mark = sheet === worst && failed ? '  ✗' : '';
         console.log(`  ${sheet.file.padEnd(width - 2)}   ${gz(sheet.gzip).padStart(9)}   ${gz(cssMaxGzip).padStart(9)}${mark}`);
@@ -68,7 +68,7 @@ function printStylesheets(stylesheets, cssMaxGzip, failed, width) {
 function printSsrNote(expected) {
     if (expected.ssr.length === 0)
         return;
-    console.log(`\nNOTE  ${expected.ssr.length} page(s) opted out with \`export const prerender = false\` and are outside this budget:`);
+    console.log(`\nNOTA  ${expected.ssr.length} pagina/e con \`export const prerender = false\`, fuori da questo budget:`);
     for (const file of expected.ssr)
         console.log(`      - ${file}`);
 }
@@ -79,7 +79,7 @@ export async function main() {
     const expected = expectedRoutes(readPageFiles(PAGES), PAGES);
     const failures = missingRouteFailures(expected, pages.map((page) => page.route), DIST);
     failures.push(...overBudgetFailures(pages));
-    const width = Math.max('ROUTE'.length, ...pages.map((p) => p.route.length));
+    const width = Math.max('ROTTA'.length, ...pages.map((p) => p.route.length));
     printPages(pages, width);
     const stylesheets = readStylesheets();
     const cssFailure = cssBudgetFailure(stylesheets, cssMaxGzip);
@@ -88,10 +88,10 @@ export async function main() {
     printStylesheets(stylesheets, cssMaxGzip, cssFailure !== null, width);
     printSsrNote(expected);
     if (failures.length > 0) {
-        console.error(`\n✗ Bundle budget:\n${failures.map((f) => `  - ${f}`).join('\n')}\n`);
+        console.error(`\n✗ Budget di bundle:\n${failures.map((f) => `  - ${f}`).join('\n')}\n`);
         return 1;
     }
-    console.log('\n✓ Bundle budget respected on every expected route.\n');
+    console.log('\n✓ Budget di bundle rispettato su ogni rotta attesa.\n');
     return 0;
 }
 if (import.meta.main)

package/dist/checks/doctor.d.ts

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

package/dist/checks/doctor.js

@@ -1,15 +1,52 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import process from 'node:process';
+import { configGaps, dependencyGaps, leftoverGaps, presetGaps, scriptGaps, workflowGaps, } from '../lib/alignment.js';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
-import { CONTRACT, contractGaps } from '../lib/contract.js';
-export function main() {
-    const findings = contractGaps(process.cwd()).map((gap) => ({ ...gap, severity: 'error' }));
-    console.log(`\nofficina doctor — ${CONTRACT.length} punti di aggancio dei generatori\n`);
-    printFindings(findings, cliOptions([]).format);
+import { findConfigFile, loadConfig } from '../lib/config.js';
+import { contractGaps } from '../lib/contract.js';
+import { trackedAndUntracked } from '../lib/git.js';
+function projectFiles(root) {
+    return {
+        paths: trackedAndUntracked(),
+        read: (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined),
+    };
+}
+async function loadedConfig(root) {
+    if (findConfigFile(root) === undefined)
+        return undefined;
+    try {
+        return await loadConfig(root);
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function main() {
+    const root = process.cwd();
+    const files = projectFiles(root);
+    const manifest = JSON.parse(files.read('package.json') ?? '{}');
+    const sections = [
+        ['punti di aggancio dei generatori', contractGaps(root)],
+        ['script e dipendenze di package.json', [...scriptGaps(manifest), ...dependencyGaps(manifest)]],
+        ['residui di ciò che è uscito dal repository', leftoverGaps(files)],
+        ['preset di configurazione', presetGaps(files)],
+        ['workflow di GitHub', workflowGaps(files)],
+        ['officina.config.ts', configGaps(await loadedConfig(root))],
+    ];
+    console.log('\nofficina doctor — cosa manca al progetto per prendere tutto da fuori\n');
+    const findings = [];
+    for (const [title, gaps] of sections) {
+        console.log(gaps.length === 0 ? `  ✓ ${title}` : `  ${title}: ${gaps.length}`);
+        const sectionFindings = gaps.map((gap) => ({ ...gap, severity: 'error' }));
+        printFindings(sectionFindings, cliOptions([]).format);
+        findings.push(...sectionFindings);
+    }
     console.log(findings.length === 0
-        ? '  Il progetto ha tutto quello che i generatori si aspettano.\n'
-        : `\n  ${findings.length} su ${CONTRACT.length} da sistemare prima che \`officina gen\` scriva codice che compila.\n`);
+        ? '\n  Il progetto è allineato: metodo, gate, generatori e verifiche arrivano da fuori.\n'
+        : `\n  ${findings.length} da sistemare.\n`);
     return exitCode(findings, false);
 }
 if (import.meta.main)
-    process.exit(main());
+    process.exit(await main());

package/dist/checks/lighthouse.js

@@ -22,7 +22,7 @@ export function main(args = []) {
     const rc = JSON.parse(readFileSync(RC_FILE, 'utf8'));
     const routes = auditRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR));
     const resolved = lighthouseConfig(rc, routes, process.env);
-    console.log(`\nLighthouse CI — ${routes.length} route(s) derived from ${PAGES_DIR}\n`);
+    console.log(`\nLighthouse CI — ${routes.length} rotta/e derivate da ${PAGES_DIR}\n`);
     for (const url of resolved.ci.collect.url ?? [])
         console.log(`  ${url}`);
     console.log();

package/dist/checks/smoke.js

@@ -10,26 +10,26 @@ function printResults(results) {
         if (status === 'pass')
             console.log(`✓ ${check}`);
         else if (status === 'skip')
-            console.log(`- ${check} (skipped: ${detail})`);
+            console.log(`- ${check} (saltato: ${detail})`);
         else
             console.error(`✗ ${check} — ${detail}`);
     }
 }
 function printFailures(failures) {
-    console.error(`\n✗ ${failures.length} check(s) failed:`);
+    console.error(`\n✗ ${failures.length} controllo/i falliti:`);
     console.error(`${failures.map(({ check, detail }) => `  - ${check} — ${detail}`).join('\n')}\n`);
-    console.error('Production is live and broken. Roll back from the Vercel dashboard:');
-    console.error('Deployments → the last known-good production deployment → Promote to Production.\n');
+    console.error('La produzione è online e rotta. Torna indietro dalla dashboard di Vercel:');
+    console.error('Deployments → l’ultimo deployment di produzione sano → Promote to Production.\n');
 }
 export async function main(args = []) {
     const { siteUrl, smoke = {} } = await loadConfig(process.cwd());
     const [url] = args;
     if (siteUrl === undefined) {
-        console.error('\n✗ officina.config.ts declares no siteUrl — the canonical-host check has nothing to compare against.\n');
+        console.error('\n✗ officina.config.ts non dichiara siteUrl: il controllo dell’host canonico non ha con cosa confrontarsi.\n');
         return 1;
     }
     if (url === undefined && new URL(siteUrl).host === 'example.com') {
-        console.error('\n✗ siteUrl is still the template placeholder — pass a URL: pnpm smoke:prod https://…\n');
+        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.
@@ -41,7 +41,7 @@ export async function main(args = []) {
         securityHeaders: smoke.securityHeaders ?? SECURITY_HEADERS,
     };
     const pages = smokeRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR), smoke.nonHtmlRoutes);
-    console.log(`\nProduction smoke — ${baseUrl}\n`);
+    console.log(`\nSmoke di produzione — ${baseUrl}\n`);
     await waitForAlias(context, (ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const results = await runChecks(context, pages, smoke.checks);
     printResults(results);
@@ -50,7 +50,7 @@ export async function main(args = []) {
         printFailures(failures);
         return 1;
     }
-    console.log(`\n✓ Every check passed on ${baseUrl}.\n`);
+    console.log(`\n✓ Tutti i controlli passati su ${baseUrl}.\n`);
     return 0;
 }
 if (import.meta.main)

package/dist/checks/vercel-cli.d.ts

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

package/dist/checks/vercel-cli.js

@@ -3,19 +3,21 @@ import { readFileSync } from 'node:fs';
 import process from 'node:process';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
 import { pinFindings } from '../lib/vercel-cli-pin.js';
-const WORKFLOW = '.github/workflows/deploy.yml';
+const DEFAULT_WORKFLOW = '.github/workflows/deploy.yml';
 // Il documento `latest` porta la sola versione pubblicata; quello del pacchetto intero pesa 8 MB.
 const REGISTRY = 'https://registry.npmjs.org/vercel/latest';
 const TIMEOUT_MS = 15_000;
-export async function main() {
+// Il file è un argomento perché officina controlla il pin della propria action di deploy.
+export async function main(args = []) {
+    const workflow = args[0] ?? DEFAULT_WORKFLOW;
     const response = await fetch(REGISTRY, { signal: AbortSignal.timeout(TIMEOUT_MS) });
     if (!response.ok) {
         console.error(`✗ registry npm illeggibile: HTTP ${response.status}`);
         return 1;
     }
     const { version } = (await response.json());
-    const findings = pinFindings(readFileSync(WORKFLOW, 'utf8'), version).map((hit) => ({
-        path: WORKFLOW,
+    const findings = pinFindings(readFileSync(workflow, 'utf8'), version).map((hit) => ({
+        path: workflow,
         ...hit,
         severity: 'error',
     }));
@@ -23,8 +25,8 @@ export async function main() {
     printFindings(findings, cliOptions([]).format);
     console.log(findings.length === 0
         ? '  Il pin è sulla major pubblicata.\n'
-        : `\n  Alza il pin in ${WORKFLOW} e allinea la CLI locale alla stessa major.\n`);
+        : `\n  Alza il pin in ${workflow} e allinea la CLI locale alla stessa major.\n`);
     return exitCode(findings, false);
 }
 if (import.meta.main)
-    process.exit(await main());
+    process.exit(await main(process.argv.slice(2)));

package/dist/lib/alignment.d.ts

@@ -0,0 +1,23 @@
+import type { OfficinaConfig } from './config.ts';
+import type { ContractGap } from './contract.ts';
+export interface ProjectFiles {
+    /** Tracciati e non tracciati, senza gli ignorati: un file locale fuori da git non è un residuo. */
+    paths: readonly string[];
+    read: (path: string) => string | undefined;
+}
+export interface Manifest {
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export declare const EXPECTED_SCRIPTS: Readonly<Record<string, string>>;
+export declare const CI_STEPS: readonly string[];
+export declare function scriptGaps({ scripts }: Manifest): ContractGap[];
+export declare function dependencyGaps({ dependencies, devDependencies }: Manifest): ContractGap[];
+export declare function leftoverGaps({ paths, read }: ProjectFiles): ContractGap[];
+export declare const BIOME_PRESET = "@elia97/officina/biome";
+export declare const LEFTHOOK_PRESET = "node_modules/@elia97/officina/presets/lefthook.yml";
+export declare function presetGaps({ read }: ProjectFiles): ContractGap[];
+export declare function workflowGaps({ read }: ProjectFiles): ContractGap[];
+/** `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se il file non c'è. */
+export declare function configGaps(loaded: OfficinaConfig | Error | undefined): ContractGap[];

package/dist/lib/alignment.js

@@ -0,0 +1,166 @@
+export const EXPECTED_SCRIPTS = {
+    'check:comments': 'officina check comments',
+    'check:language': 'officina check language',
+    'check:routes': 'officina check routes',
+    'check:roadmap': 'officina check roadmap',
+    'check:placeholders': 'officina check placeholders',
+    'perf:bundle': 'officina check bundle',
+    'smoke:prod': 'officina check smoke',
+    'analytics:verify': 'officina check analytics',
+    lhci: 'officina check lighthouse',
+    'lhci:local': 'officina check lighthouse --local',
+    doctor: 'officina doctor',
+    gen: 'officina gen',
+    'gen:section': 'officina gen section',
+    'gen:page': 'officina gen page',
+    'gen:component': 'officina gen component',
+    'gen:collection': 'officina gen collection',
+    'gen:icons': 'officina gen icons',
+};
+export const CI_STEPS = [
+    'check:language',
+    'check:routes',
+    'check:roadmap',
+    'check:comments',
+    'doctor',
+];
+const MANIFEST = 'package.json';
+export function scriptGaps({ scripts = {} }) {
+    const gaps = [];
+    for (const [name, expected] of Object.entries(EXPECTED_SCRIPTS)) {
+        const actual = scripts[name];
+        if (actual === undefined)
+            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}\`` });
+    }
+    const ci = scripts.ci ?? '';
+    for (const step of CI_STEPS) {
+        if (!ci.includes(`pnpm run ${step}`))
+            gaps.push({ path: MANIFEST, message: `script \`ci\` non lancia \`${step}\`` });
+    }
+    return gaps;
+}
+const RETIRED_DEPENDENCIES = ['plop', 'ts-morph'];
+export function dependencyGaps({ dependencies = {}, devDependencies = {} }) {
+    const declared = { ...dependencies, ...devDependencies };
+    const gaps = RETIRED_DEPENDENCIES.filter((name) => name in declared).map((name) => ({
+        path: MANIFEST,
+        message: `\`${name}\` non serve più al progetto: è una dipendenza di officina`,
+    }));
+    if (!('@elia97/officina' in devDependencies)) {
+        gaps.push({ path: MANIFEST, message: '`@elia97/officina` non è fra le devDependencies' });
+    }
+    return gaps;
+}
+const FROM_PLUGIN = 'arriva dal plugin `metodo`';
+const FROM_PACKAGE = 'arriva da officina';
+const OUT_OF_REPOSITORY = 'sta nella cartella del progetto, fuori dal repository';
+// Una cartella si nomina con la barra finale: corrisponde a qualunque file sotto di lei.
+const LEFTOVERS = [
+    { path: '.claude/agents/', reason: FROM_PLUGIN },
+    { path: '.claude/commands/', reason: FROM_PLUGIN },
+    { path: '.claude/scripts/', reason: FROM_PLUGIN },
+    { path: '.claude/hooks/', reason: FROM_PLUGIN },
+    { path: 'HOW_TO_USE.md', reason: FROM_PLUGIN },
+    { path: 'docs/milestone-templates/', reason: FROM_PLUGIN },
+    { path: 'docs/proposal-templates/', reason: 'i modelli commerciali stanno nel sistema, non nel repository' },
+    { path: 'plopfile.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen/', reason: FROM_PACKAGE },
+    { path: 'scripts/templates/', reason: FROM_PACKAGE },
+    { path: 'scripts/check-comments.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/check-language.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/bundle-budget.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/smoke-production.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/lighthouse.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/verify-analytics-coverage.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen-icons.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen-icons.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lhci-local.sh', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/bundle-budget.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/smoke-production.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/routes.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/check-comments.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/check-language.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/gtm-container.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/analytics-coverage.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/icons.ts', reason: FROM_PACKAGE },
+    { path: '.github/workflows/vercel-cli.yml', reason: "il pin di Vercel sta nell'action di deploy di officina" },
+    { path: 'docs/PROJECT.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/DECISIONS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/RISKS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/INPUTS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/TASK-CONTEXT.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/ESTIMATE.md', reason: OUT_OF_REPOSITORY },
+];
+const holds = (paths, target) => target.endsWith('/') ? paths.some((path) => path.startsWith(target)) : paths.includes(target);
+export function leftoverGaps({ paths, read }) {
+    const gaps = LEFTOVERS.filter(({ path }) => holds(paths, path)).map(({ path, reason }) => ({
+        path,
+        message: `residuo: ${reason}`,
+    }));
+    if (read('.claude/settings.json')?.includes('"hooks"')) {
+        gaps.push({ path: '.claude/settings.json', message: `blocco \`hooks\` residuo: il guard ${FROM_PLUGIN}` });
+    }
+    if (read('.mcp.json')?.includes('astro-docs')) {
+        gaps.push({ path: '.mcp.json', message: `server \`astro-docs\` residuo: ${FROM_PLUGIN}` });
+    }
+    return gaps;
+}
+export const BIOME_PRESET = '@elia97/officina/biome';
+export const LEFTHOOK_PRESET = 'node_modules/@elia97/officina/presets/lefthook.yml';
+export function presetGaps({ read }) {
+    const gaps = [];
+    if (!read('biome.json')?.includes(BIOME_PRESET)) {
+        gaps.push({ path: 'biome.json', message: `non estende \`${BIOME_PRESET}\`` });
+    }
+    if (!read('lefthook.yml')?.includes(LEFTHOOK_PRESET)) {
+        gaps.push({ path: 'lefthook.yml', message: `non estende \`${LEFTHOOK_PRESET}\`` });
+    }
+    return gaps;
+}
+const ACTIONS = [
+    { workflow: '.github/workflows/ci.yml', action: 'ci' },
+    { workflow: '.github/workflows/ci.yml', action: 'review' },
+    { workflow: '.github/workflows/deploy.yml', action: 'deploy' },
+    { workflow: '.github/workflows/lighthouse.yml', action: 'lighthouse' },
+];
+// Un tag di versione o uno SHA intero: `@main` farebbe girare in produzione passi mai collaudati.
+const PINNED_REF = /^(v\d+\.\d+\.\d+|[0-9a-f]{40})$/;
+function actionGap(source, action) {
+    const name = `Elia97/officina/actions/${action}`;
+    if (source === undefined)
+        return `manca: i suoi passi arrivano da \`${name}\``;
+    const ref = new RegExp(`${name}@(\\S+)`).exec(source)?.[1];
+    if (ref === undefined)
+        return `non usa \`${name}\``;
+    return PINNED_REF.test(ref)
+        ? undefined
+        : `\`${name}@${ref}\`: il riferimento va fissato a un tag di versione o a uno SHA`;
+}
+export function workflowGaps({ read }) {
+    return ACTIONS.flatMap(({ workflow, action }) => {
+        const message = actionGap(read(workflow), action);
+        return message === undefined ? [] : [{ path: workflow, message }];
+    });
+}
+const CONFIG = 'officina.config.ts';
+function siteUrlGap(siteUrl) {
+    if (siteUrl === undefined)
+        return '`siteUrl` assente: `check smoke` non ha un host canonico';
+    if (!URL.canParse(siteUrl))
+        return `\`siteUrl\` non è un URL: \`${siteUrl}\``;
+    return siteUrl.endsWith('/') ? `\`siteUrl\` finisce con una barra: \`${siteUrl}\`` : undefined;
+}
+/** `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se il file non c'è. */
+export function configGaps(loaded) {
+    if (loaded === undefined)
+        return [{ path: CONFIG, message: 'manca: i valori del progetto per officina stanno qui' }];
+    if (loaded instanceof Error)
+        return [{ path: CONFIG, message: `non si carica: ${loaded.message}` }];
+    const messages = [
+        siteUrlGap(loaded.siteUrl),
+        loaded.icons === undefined ? '`icons.background` assente: `gen icons` non ha un colore di fondo' : undefined,
+    ];
+    return messages.filter((message) => message !== undefined).map((message) => ({ path: CONFIG, message }));
+}

package/dist/lib/config.d.ts

@@ -21,4 +21,5 @@ export interface OfficinaConfig {
     };
 }
 export declare const defineConfig: (config: OfficinaConfig) => OfficinaConfig;
+export declare const findConfigFile: (root: string) => string | undefined;
 export declare function loadConfig(root: string): Promise<OfficinaConfig>;

package/dist/lib/config.js

@@ -12,8 +12,9 @@ import { pathToFileURL } from 'node:url';
 const CONFIG_FILES = ['officina.config.ts', 'officina.config.mjs', 'officina.config.js'];
 export const defineConfig = (config) => config;
 // Fuori da node_modules Node toglie i tipi da solo: il file del progetto può essere TypeScript.
+export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find((path) => existsSync(path));
 export async function loadConfig(root) {
-    const file = CONFIG_FILES.map((name) => join(root, name)).find((path) => existsSync(path));
+    const file = findConfigFile(root);
     if (file === undefined)
         return {};
     const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));

package/dist/lib/routes.js

@@ -66,18 +66,18 @@ export function expectedRoutes(pages, pagesDir) {
 /** [HARD] Guardia fail-open: ogni asserzione per rotta itera sulle pagine emesse, quindi una dist vuota non asserisce niente. */
 export function missingRouteFailures(expected, emitted, dist) {
     if (emitted.length === 0) {
-        return [`${dist} holds no .html file — no route was measured, so the per-route budgets assert nothing`];
+        return [`${dist} non contiene nessun .html: nessuna rotta misurata, quindi i budget per rotta non affermano niente`];
     }
     const failures = [];
     const routes = new Set(emitted);
     for (const { route, file } of expected.exact) {
         if (!routes.has(route))
-            failures.push(`missing route ${route} — ${file} is prerendered but emitted no HTML`);
+            failures.push(`rotta mancante ${route}: ${file} è prerenderizzata ma non ha emesso HTML`);
     }
     for (const { pattern, label, file } of expected.patterns) {
         if (emitted.some((route) => pattern.test(route)))
             continue;
-        failures.push(`missing route ${label} — ${file} is prerendered but getStaticPaths emitted nothing`);
+        failures.push(`rotta mancante ${label}: ${file} è prerenderizzata ma getStaticPaths non ha emesso niente`);
     }
     return failures;
 }

package/dist/lib/smoke-production.js

@@ -33,9 +33,9 @@ export async function checkPages({ get, baseUrl }, pages) {
             const response = await get(`${baseUrl}${path}`);
             const contentType = response.headers.get('content-type') ?? '';
             if (response.status !== 200)
-                results.push(fail(check, `expected 200, got ${response.status}`));
+                results.push(fail(check, `atteso 200, ricevuto ${response.status}`));
             else if (!contentType.includes(type))
-                results.push(fail(check, `expected a ${type} content-type, got "${contentType}"`));
+                results.push(fail(check, `atteso un content-type ${type}, ricevuto "${contentType}"`));
             else
                 results.push(pass(check));
         }
@@ -51,29 +51,29 @@ export async function checkSecurityHeaders({ get, baseUrl, securityHeaders }) {
         response = await get(baseUrl);
     }
     catch (error) {
-        return [fail('security headers', messageOf(error))];
+        return [fail('header di sicurezza', messageOf(error))];
     }
     const results = Object.entries(securityHeaders).map(([header, expected]) => {
         const check = `header ${header}`;
         const value = response.headers.get(header);
         if (value === null)
-            return fail(check, 'missing');
+            return fail(check, 'assente');
         if (expected !== null && value !== expected)
-            return fail(check, `expected "${expected}", got "${value}"`);
+            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 = 'no x-robots-tag on the production host';
+    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, `present on ${baseUrl}: "${robots}"`));
+    results.push(robots === null ? pass(check) : fail(check, `presente su ${baseUrl}: "${robots}"`));
     return results;
 }
 export async function checkBotIdChallenge({ get, baseUrl }) {
-    const check = 'BotID challenge proxied same-origin';
+    const check = 'challenge di BotID servita dalla stessa origine';
     try {
         const response = await get(`${baseUrl}${BOTID_CHALLENGE}`);
         if (response.status !== 200)
-            return [fail(check, `expected 200 from the rewrite, got ${response.status}`)];
+            return [fail(check, `atteso 200 dal rewrite, ricevuto ${response.status}`)];
         return [pass(check)];
     }
     catch (error) {
@@ -82,16 +82,16 @@ export async function checkBotIdChallenge({ get, baseUrl }) {
 }
 /** Il 308 da www all'apice, da vercel.json: dipende dal DNS e dal dominio del progetto Vercel, non dal deployment. */
 export async function checkCanonicalHost({ get, baseUrl, siteUrl }) {
-    const check = 'www → apex 308';
+    const check = 'www → apice 308';
     if (baseUrl !== siteUrl)
-        return [skip(check, `base URL is not ${siteUrl}`)];
+        return [skip(check, `l’URL di base non è ${siteUrl}`)];
     try {
         const response = await get(`https://www.${new URL(siteUrl).host}/`);
         const location = response.headers.get('location') ?? '';
         if (response.status !== 308)
-            return [fail(check, `expected 308, got ${response.status}`)];
+            return [fail(check, `atteso 308, ricevuto ${response.status}`)];
         if (!location.startsWith(siteUrl))
-            return [fail(check, `location "${location}" does not point at ${siteUrl}`)];
+            return [fail(check, `location "${location}" non punta a ${siteUrl}`)];
         return [pass(check)];
     }
     catch (error) {
@@ -100,16 +100,16 @@ export async function checkCanonicalHost({ get, baseUrl, siteUrl }) {
 }
 export async function checkTrailingSlash({ get, baseUrl }, pages) {
     const page = pages.find(({ path, type }) => type === 'text/html' && path !== '/');
-    const check = 'trailing slash → 308';
+    const check = 'barra finale → 308';
     if (page === undefined)
-        return [skip(check, 'no HTML page other than / to probe')];
+        return [skip(check, 'nessuna pagina HTML oltre a / da sondare')];
     try {
         const response = await get(`${baseUrl}${page.path}/`);
         if (response.status !== 308)
-            return [fail(check, `expected 308 on ${page.path}/, got ${response.status}`)];
+            return [fail(check, `atteso 308 su ${page.path}/, ricevuto ${response.status}`)];
         const location = response.headers.get('location') ?? '';
         if (!location.endsWith(page.path))
-            return [fail(check, `location "${location}" does not point at ${page.path}`)];
+            return [fail(check, `location "${location}" non punta a ${page.path}`)];
         return [pass(check)];
     }
     catch (error) {

package/dist/sh/lhci-local.sh

@@ -25,9 +25,9 @@ detect_chrome() {
 }
 
 if ! CHROME_PATH="$(detect_chrome)"; then
-  echo "✗ no usable Linux Chrome/Chromium found." >&2
-  echo "  Install one with: pnpm dlx playwright@latest install chromium" >&2
-  echo "  Or point at the binary: CHROME_PATH=/path/to/chrome pnpm run lhci:local" >&2
+  echo "✗ nessun Chrome/Chromium per Linux utilizzabile." >&2
+  echo "  Installane uno con: pnpm dlx playwright@latest install chromium" >&2
+  echo "  Oppure indica il binario: CHROME_PATH=/percorso/di/chrome pnpm run lhci:local" >&2
   exit 1
 fi
 export CHROME_PATH
@@ -44,17 +44,17 @@ cleanup() {
 }
 trap cleanup EXIT
 
-echo "→ production-equivalent build in ${OUT_DIR}"
+echo "→ build equivalente alla produzione in ${OUT_DIR}"
 VERCEL_ENV=production pnpm build --outDir "${OUT_DIR}"
 
 if ! grep -qx 'Allow: /' "${OUT_DIR}/client/robots.txt"; then
-  echo "✗ ${OUT_DIR}/client/robots.txt has no 'Allow: /' — the build is not production-equivalent." >&2
+  echo "✗ ${OUT_DIR}/client/robots.txt non ha 'Allow: /': la build non equivale alla produzione." >&2
   head -3 "${OUT_DIR}/client/robots.txt" >&2
   exit 1
 fi
 echo "✓ robots.txt: Allow: /"
 
-echo "→ starting the static server on :${PORT}"
+echo "→ avvio del server statico su :${PORT}"
 setsid pnpm dlx serve@14 "${OUT_DIR}/client" --listen "${PORT}" --no-clipboard >/dev/null 2>&1 &
 SERVER_PID=$!
 
@@ -63,11 +63,11 @@ for _ in $(seq 1 60); do
   sleep 1
 done
 if ! curl -fs -o /dev/null "http://localhost:${PORT}/"; then
-  echo "✗ the server did not answer on :${PORT} within 60s." >&2
-  echo "  Retry on another port: LHCI_PORT=4400 pnpm run lhci:local" >&2
+  echo "✗ il server non ha risposto su :${PORT} entro 60s." >&2
+  echo "  Riprova su un’altra porta: LHCI_PORT=4400 pnpm run lhci:local" >&2
   exit 1
 fi
-echo "✓ server ready"
+echo "✓ server pronto"
 
 rm -rf "${REPORT_DIR}"
 
@@ -79,7 +79,7 @@ LH_CHROME_FLAGS='--no-sandbox --disable-dev-shm-usage' \
   node "${OFFICINA_BIN}" check lighthouse
 
 echo
-echo "→ score per URL (median over ${LHCI_RUNS:-1} run(s), the way LHCI asserts)"
+echo "→ punteggio per URL (mediana su ${LHCI_RUNS:-1} giro/i, come la calcola LHCI)"
 node -e '
 const fs = require("fs")
 const dir = process.argv[1]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elia97/officina",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -12,13 +12,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./biome": "./presets/biome.base.json"
   },
   "bin": {
     "officina": "dist/bin.js"
   },
   "files": [
     "dist",
+    "presets",
     "README.md"
   ],
   "engines": {

package/presets/biome.base.json

@@ -0,0 +1,100 @@
+{
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!!**/dist",
+      "!!**/public",
+      "!!.claude/worktrees",
+      "!!src/assets/**/*.svg",
+      "!!.release-please-manifest.json"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "style": {
+        "noExcessiveLinesPerFile": {
+          "level": "error",
+          "options": {
+            "maxLines": 200
+          }
+        }
+      },
+      "complexity": {
+        "noExcessiveLinesPerFunction": "error"
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "error",
+          "options": {
+            "functions": ["cn", "cva"]
+          }
+        }
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on",
+          "options": {
+            "groups": [
+              [":PACKAGE_WITH_PROTOCOL:", ":PACKAGE:"],
+              ":BLANK_LINE:",
+              ["@/components/**"],
+              ":BLANK_LINE:",
+              ["@/layouts/**"],
+              ":BLANK_LINE:",
+              ["@/lib/**"],
+              ":BLANK_LINE:",
+              ["@/i18n", "@/i18n/**"],
+              ":BLANK_LINE:",
+              ["@/actions", "@/actions/**"],
+              ":BLANK_LINE:",
+              ["@/emails/**"],
+              ":BLANK_LINE:",
+              ":PATH:"
+            ]
+          }
+        }
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.astro"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUnusedVariables": "off",
+            "noUnusedImports": "off"
+          }
+        }
+      }
+    }
+  ]
+}

package/presets/lefthook.yml

@@ -0,0 +1,11 @@
+pre-commit:
+  commands:
+    biome-check:
+      glob: "*.{js,jsx,ts,tsx,astro,json,jsonc,css}"
+      run: pnpm -s biome:fix {staged_files}
+      stage_fixed: true
+
+commit-msg:
+  commands:
+    commitlint:
+      run: pnpm exec commitlint --edit {1}