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>
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 di progetto:
docs/BRIEF.md· Mockup:docs/mockups/ - Decisioni tecniche:
DECISIONS.md· Dati da fornire:TODO-STUDIO.md· Novità:CHANGELOG.md - Wiki del repository (come vedere e provare il sito, CI e release, dati da fornire): Wiki · Release: v1.0.0
- Pubblicazione sull'hosting:
docs/DEPLOY.md· Aggiornare i contenuti:docs/CONTENUTI.md· Conformità:docs/CONFORMITA.md
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
-
Aggiornare
versioninpackage.json(SemVer:1.0.1correzioni,1.1.0novità,2.0.0cambiamenti importanti) enpm installper allinearepackage-lock.json. -
Aggiungere in
CHANGELOG.mdla sezione## [X.Y.Z] - AAAA-MM-GG: diventa il testo della release. -
npm run verify, commit (chore(release): prepara vX.Y.Z) e push sumain. -
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 connpm run iconsdopo modifiche al marchio; i file generati vanno committati. - Telemetria di Astro: disattivata in CI (
ASTRO_TELEMETRY_DISABLED=1); in localenpx astro telemetry disable. - Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.