Alby96andClaude Opus 5.5 3befe7e266 fix: CI adattata a Forgejo, revisione completa del codice e avvio in debug
Le run della CI restavano «in attesa» perché l'unico runner dell'istanza («Ferrari») non si è
mai collegato: il runner resta da configurare. La revisione completa del codice ha trovato
anche difetti che avrebbero fatto fallire la CI con il runner online, oltre ad altri problemi
del sito, dei controlli e della documentazione.

CI e rilascio:
- continue-on-error sullo step dei link esterni: Forgejo lo ignora sul job, e un sito esterno
  irraggiungibile avrebbe reso rossa la CI;
- artifact con i file nascosti (report Lighthouse e .htaccess non venivano mai caricati);
- token personale RELEASE_TOKEN: FORGEJO_TOKEN è riservato ed è sempre il token automatico;
- dominio in un solo punto (site.config.mjs) e variabile del repository SITE_URL;
- ripiego REST: release in bozza, file, poi pubblicazione; tag verificato sul server;
  sostituzione dei file senza mai lasciarli mancanti;
- tar.gz identico su Windows, macOS e Linux (byte del sistema operativo nell'header gzip).

Sito: CSS compatibile con Safari/iOS 15 (media query classiche, backdrop-filter), anello di
focus con contrasto di almeno 3:1, bersagli touch di 44 px dove servono, intestazione desktop
senza voci o logo a capo, HTML valido in /servizi/, colore delle chip, stampa senza mappe,
giorni di apertura, ricerca e titolo delle mappe e numero breve ricavati dai dati.

Modulo di contatto e contact.php: stesse regole nel browser e sul server (spazi, e-mail,
a capo, lunghezze), tempo minimo misurato con un solo orologio (ts_invio), corpo in
quoted-printable e oggetto RFC 2047, funzionamento con PHP a 32 bit, costante
MODALITA_PREDEFINITA per attivarlo.

Controlli e test: valori letti dai dati del sito, i sei servizi del brief con le ancore,
«commercialista» anche in meta, attributi e dati strutturati, .htaccess su righe attive,
HSTS attivabile con una scelta esplicita, contrasto del focus misurato nei test.

Esempi di pubblicazione: nginx con gli header di sicurezza in un solo punto (HSTS compreso),
deploy automatico che parte alla pubblicazione e sincronizza solo una cartella confermata,
procedura nginx che toglie i file delle versioni precedenti.

Debug: .vscode/launch.json e tasks.json, F5 avvia il server Astro e apre il browser con il
debugger collegato.

Documentazione aggiornata (README, DEPLOY, CONTENUTI, CONFORMITA, TODO-STUDIO, CHANGELOG) e
decisioni D-045…D-055.

Verificato: npm run verify su Windows e nel container della CI (Playwright 1.56.1, root);
job dei link esterni in node:24; contact.php con PHP 7.4 e 8.3, a 64 e 32 bit; nginx in
Docker; release-upload.sh e deploy di esempio contro API e shell simulate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 13:40:16 +02:00

Sito web dello Studio Grasso

Sito statico dello Studio Grasso — Studio Tributario e Societario (Montegrosso d'Asti e Asti), realizzato con Astro. Nessun tracciamento, nessun cookie, nessuna risorsa di terze parti caricata senza un'azione esplicita dell'utente; pacchetto di rilascio universale (solo file statici, con .htaccess) pronto per qualsiasi hosting.

Requisiti

  • Node.js LTS: versione in .nvmrc (24), minimo 22.22.3. Con nvm: nvm install && nvm use.
  • npm (incluso in Node.js).
  • Per i test: Chromium di Playwright. Se manca: npx playwright install --with-deps chromium (una volta sola).

Avvio rapido

npm ci            # installa le dipendenze esatte di package-lock.json
npm run dev       # sito in sviluppo su http://localhost:4321 (si aggiorna a ogni modifica)
npm run build     # genera il sito statico in dist/
npm run preview   # serve dist/ su http://127.0.0.1:4321
npm run verify    # tutti i controlli di qualità (gli stessi della CI)
npm run package   # crea il pacchetto di rilascio in release/

Avvio in debug con VS Code

Dopo npm ci, aprire il pannello Esegui e debug (Ctrl+Maiusc+D), scegliere una configurazione e premere F5:

Configurazione Cosa fa
Sito: sviluppo (Edge) / (Chrome) astro dev con il debugger di Node; quando il server è pronto apre il browser con il debugger collegato (punti di interruzione negli script di src/scripts/)
Sito: anteprima della build (Edge) esegue npm run build e serve dist/ come in produzione su http://127.0.0.1:4321

Maiusc+F5 ferma il server e chiude il browser quando è selezionata la sessione del server, come all'avvio. Dopo una pausa su un punto di interruzione nel browser è selezionata la sessione del browser, e Maiusc+F5 chiude solo quella: premerlo una seconda volta, oppure usare Stop sulla sessione «Sito: sviluppo» nel pannello dello stack di chiamate. Le configurazioni sono in .vscode/launch.json e .vscode/tasks.json. Astro avvia un solo server di sviluppo per progetto: se npm run dev è già aperto in un terminale, chiuderlo prima di premere F5.

Comandi

Comando Cosa fa
npm run dev server di sviluppo
npm run build build statica in dist/
npm run preview anteprima di dist/
npm run lint ESLint (JavaScript, TypeScript, Astro)
npm run format / format:check Prettier: corregge / verifica la formattazione
npm run check astro check: tipi TypeScript e componenti
npm run test:html validità HTML di tutte le pagine (html-validate)
npm run test:links link interni, asset e ancore (linkinator); -- --external anche i siti esterni
npm run test:e2e test end-to-end (Playwright): pagine, navigazione, menu, privacy, mappa, modulo
npm run test:a11y accessibilità: axe su tutte le pagine a 1440 e 390 px, tastiera, zoom, reflow
npm run test:compliance conformità (P.IVA, pagine legali, nessun tracciamento, JSON-LD, titoli professionali…)
npm run test:lighthouse Lighthouse CI: Performance ≥ 0.95, Accessibility 1, Best Practices ≥ 0.95, SEO 1
npm test html + link + e2e + a11y + conformità
npm run verify lint + formattazione + tipi + build + npm test + Lighthouse
npm run package build + pacchetto in release/ + verifica del pacchetto (test:package)
npm run icons rigenera marchio, favicon, apple-touch-icon e immagine di condivisione

npm run verify deve terminare senza errori prima di ogni rilascio: è il comando eseguito dalla CI.

Struttura

src/data/          dati e testi: studio.ts (anagrafica, sedi, orari, professionisti, abilitazioni,
                   partner, modulo), pagine.ts (testi delle pagine), testi.ts, navigazione.ts
src/content/       servizi/*.md, legali/*.md (privacy, cookie, note legali, accessibilità),
                   link-utili.json — schemi in src/content.config.ts
src/components/    componenti Astro (intestazione, footer, card, mappa, modulo…)
src/layouts/       BaseLayout.astro: <head>, SEO, dati strutturati, struttura della pagina
src/pages/         una pagina per file; servizi/[slug].astro genera le 6 pagine dei servizi
src/styles/        tokens.css (colori, tipografia, spaziature), global.css, fonts.css, print.css
src/scripts/       piccoli script: menu, mappa su consenso, modulo, ancore del vecchio sito
public/            .htaccess, favicon e immagini statiche (copiati così come sono)
scripts/           script di test, pacchetto, icone, note di rilascio, upload della release
tests/             e2e/ e a11y/ (Playwright), helpers/
deploy/            nginx.conf.example, optional-php-form/contact.php, esempio di deploy automatico
.forgejo/workflows ci.yml (verifica) e release.yml (pubblicazione della release)
.vscode/           launch.json e tasks.json: avvio del sito in debug (F5)
docs/              brief, mockup, guide di deploy e contenuti, conformità
site.config.mjs    dominio pubblico del sito (unica fonte per build, test e pacchetto)

Configurazione

Impostazione Dove Valore predefinito
Dominio del sito (canonical, sitemap, robots, dati strutturati) site.config.mjs, oppure variabile SITE_URL (in CI: variabile del repository SITE_URL) https://www.grassoezio.it
Modulo di contatto: off, php, endpoint MODALITA_PREDEFINITA in src/data/studio.ts, oppure variabile CONTACT_FORM_MODE off (card «Scrivici una e-mail»)
Data riproducibile (anno nel footer, date negli archivi) variabile SOURCE_DATE_EPOCH ora corrente / data dell'ultimo commit

Le variabili valgono per tutti i comandi della sessione (build, verify, package), non solo per la build. Esempio, nel terminale di VS Code (PowerShell):

$env:SITE_URL = 'https://studiograssoezio.it'
npm run verify
Remove-Item Env:SITE_URL

In Git Bash, macOS o Linux: SITE_URL=https://studiograssoezio.it npm run verify. Per un cambio di dominio definitivo modificare invece il valore in site.config.mjs, oppure la variabile del repository SITE_URL su Forgejo (Impostazioni → Actions → Variabili), che CI e release usano per la build.

Per verificare il modulo attivo (validazione, anti-spam, pagina di conferma), in PowerShell:

$env:CONTACT_FORM_MODE = 'php'
npm run build
npx playwright test tests/e2e/form.spec.ts
Remove-Item Env:CONTACT_FORM_MODE
npm run build   # ripristina la versione senza modulo

In Git Bash, macOS o Linux: CONTACT_FORM_MODE=php npm run build && npx playwright test tests/e2e/form.spec.ts && npm run build.

Pubblicare il repository su Forgejo

Questo repository è un clone di https://forgejo.encke-hake.ts.net/BalboSoft/Studio_Grasso.git: il remote origin è già configurato. Per un repository nuovo: git remote add origin <url-del-repository>.

git push -u origin main          # pubblica il codice: parte la CI (.forgejo/workflows/ci.yml)

Consigliato: proteggere il branch main (Impostazioni del repository → Branch → Protezione: niente push forzati, merge solo con CI verde) e lavorare con branch e pull request. I messaggi di commit seguono Conventional Commits in italiano (feat:, fix:, docs:, ci:, test:, chore:).

La CI richiede un runner Forgejo Actions con label docker (modificabile in cima ai file dei workflow). Le azioni sono indicate con URL completo su code.forgejo.org, quindi non dipendono dalla configurazione dell'istanza.

Fare una release

  1. Aggiornare version in package.json (SemVer: 1.0.1 correzioni, 1.1.0 novità, 2.0.0 cambiamenti importanti) e npm install per allineare package-lock.json.

  2. Aggiungere in CHANGELOG.md la sezione ## [X.Y.Z] - AAAA-MM-GG: diventa il testo della release.

  3. npm run verify, commit (chore(release): prepara vX.Y.Z) e push su main.

  4. Creare e pubblicare il tag:

    git tag vX.Y.Z
    git push origin vX.Y.Z
    

Il workflow release.yml verifica che tag, package.json e CHANGELOG coincidano, esegue npm run verify e npm run package e pubblica nella sezione Release del repository: sito-studio-grasso-vX.Y.Z.zip, .tar.gz, SHA256SUMS.txt, BUILD-INFO.txt.

Token: per impostazione predefinita la release è pubblicata con il token automatico del workflow, che su Forgejo ha il permesso di scrittura sul repository. Per usare un token personale (necessario per avviare in automatico il deploy facoltativo, docs/DEPLOY.md sezione 9, perché le modifiche fatte con il token automatico non avviano altri workflow) creare un access token (Impostazioni utente → Applicazioni → Genera nuovo token, permesso write:repository) e salvarlo come segreto del repository RELEASE_TOKEN (Impostazioni del repository → Actions → Segreti): il workflow lo usa al posto di quello automatico. Non usare nomi che iniziano con FORGEJO_, GITEA_ o GITHUB_: Forgejo li riserva, e secrets.FORGEJO_TOKEN è sempre il token automatico.

Il workflow pubblica la release con l'action forgejo-release; se l'action non riesce, lo step successivo la pubblica con l'API REST (scripts/release-upload.sh, solo curl e node). Lo stesso script serve anche a mano (istruzioni in testa al file e in docs/DEPLOY.md).

Aggiornare le dipendenze

Le versioni sono bloccate (senza ^) e package-lock.json è committato. Per aggiornare: npm install <pacchetto>@<versione> --save-exact, poi npm run verify. Playwright: la versione di @playwright/test, playwright e playwright-core deve coincidere con l'immagine mcr.microsoft.com/playwright:vX.Y.Z-noble usata in .forgejo/workflows/ci.yml e release.yml (oggi 1.56.1).

Note

  • Le icone (favicon, og-default.png, logo) si rigenerano con npm run icons dopo modifiche al marchio; i file generati vanno committati.
  • Telemetria di Astro: disattivata in CI (ASTRO_TELEMETRY_DISABLED=1); in locale npx astro telemetry disable.
  • Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.
S
Description
Sito internet per Studio Grasso
Readme
1.6 MiB
0 Stars 1 Watchers 0 Forks
v1.1.0
Latest
2026-11-13 11:27:20 +01:00
Languages
Astro 37.8%
TypeScript 31%
JavaScript 20.1%
CSS 5.8%
PHP 3.5%
Other 1.8%