Chess Hammer

Web app per tracciare allenamenti di scacchi con il metodo del picchio: risolvi un set fisso di puzzle per 3 giri consecutivi, aumentando la velocità di risoluzione ad ogni giro.

Live: chesshammer.com

Stack

• React + TypeScript + Vite
• Tailwind CSS + shadcn/ui (Radix, preset Nova)
• Supabase (Postgres + Auth)
• TanStack Query, React Router
• chess.js + react-chessboard

Setup locale

npm install
cp .env.example .env.local   # compila VITE_SUPABASE_URL e VITE_SUPABASE_ANON_KEY
npm run dev

Progetto Supabase di sviluppo

npm run dev usa un progetto Supabase separato, chess-hammer-dev (stessa regione UE), così le prove non toccano i dati reali. Le sue impostazioni stanno in .env.development.local (non nel repo), che per npm run dev ha la precedenza su .env.local:

VITE_SUPABASE_URL=https://<ref di sviluppo>.supabase.co
VITE_SUPABASE_ANON_KEY=<chiave anon del progetto di sviluppo>
VITE_TURNSTILE_SITE_KEY=          # vuota: niente CAPTCHA in sviluppo
DEV_SUPABASE_DB_URL=postgresql://postgres.<ref>:<password>@aws-0-eu-west-1.pooler.supabase.com:5432/postgres

Il progetto di sviluppo ha CAPTCHA e conferma email disattivati, site_url http://localhost:5180, tutte le migrazioni e un campione di ~17.000 puzzle Lichess (circa 600 per fascia di rating, copiati dalla produzione). I progetti gratuiti si mettono in pausa dopo una settimana senza uso: si riattivano dal pannello di Supabase.

Script disponibili

• npm run dev — dev server

• npm run build — typecheck + build produzione

• npm run typecheck — solo typecheck

• npm run lint — oxlint

• npm run format — prettier --write

• npm run test — suite di test automatici (Vitest); deve passare prima di ogni rilascio in produzione, vedi CLAUDE.md

• npm run test:e2e — test end-to-end in Chrome (Playwright) dei flussi principali: registrazione e accesso, nuova sessione e prima mossa, cambio lingua, download dei dati, eliminazione dell'account. Avviano da soli npm run dev sulla porta 5190 e girano solo sul progetto Supabase di sviluppo (si fermano se .env.development.local manca o punta alla produzione); ogni esecuzione crea un account +e2e-… e lo elimina alla fine, e all'avvio cancella quelli rimasti da esecuzioni interrotte. Usano il Chrome già installato: nessun browser da scaricare.

Migrazioni del database

Le migrazioni in supabase/migrations/ si applicano con la Supabase CLI (brew install supabase/tap/supabase):

supabase login                                        # una volta, apre il browser
supabase link --project-ref <ref del progetto>         # una volta per checkout
supabase migration list                               # cosa è applicato e cosa no
supabase db push --dry-run                            # anteprima
supabase db push                                      # applica le migrazioni nuove

link e db push chiedono la password del database (o la leggono da SUPABASE_DB_PASSWORD). Una migrazione nuova si prova prima sul progetto di sviluppo, poi si applica alla produzione:

supabase db push --db-url "$DEV_SUPABASE_DB_URL"      # sviluppo
supabase db push                                      # produzione (progetto collegato)

Le migrazioni 0001–0026 sono state applicate a mano dal SQL Editor e poi registrate con supabase migration repair --status applied: da qui in poi lo storico è tenuto dalla CLI.

Ogni tabella nuova in public va creata insieme ai suoi GRANT (dal 30 ottobre 2026 Supabase non li dà più in automatico): vedi CLAUDE.md e la migrazione 0032.

Le prove SQL in supabase/tests/ girano solo sul progetto di sviluppo, dentro una transazione annullata alla fine (non lasciano tracce). Ad esempio, per la pausa tra i giri che finisce a mezzanotte e la quota contata nel fuso orario di chi gioca (0030):

psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/rest-start-of-day.sql
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/saved-puzzles.sql       # puzzle problematici (0031)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/table-grants.sql        # permessi delle tabelle (0032)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/practice-attempt-session.sql  # sessione dei tentativi liberi (0033)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/training-stats.sql      # statistiche dell'utente (0034)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/next-puzzle.sql         # prossimo puzzle in una chiamata (0035)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/theme-puzzles.sql       # puzzle per categoria in pratica libera (0036)
psql "$DEV_SUPABASE_DB_URL" -f supabase/tests/opening-training.sql    # allenamento sulle aperture (0100-0106)

Conservazione degli account

Ogni notte (4:30 UTC) un job pg_cron nel database esegue run_account_retention() (migrazione 0027), come promesso nell'informativa privacy:

• gli account mai confermati si eliminano 7 giorni dopo la registrazione;
• chi non usa l'account da 23 mesi riceve un'email (Resend, nella sua lingua) che annuncia l'eliminazione 30 giorni dopo; se nel frattempo accede o gioca, l'avviso si annulla;
• passati i 30 giorni, l'account si elimina con tutti i suoi dati.

"Uso" vuol dire accesso, rinnovo automatico della sessione o puzzle giocato. L'email parte solo se in Supabase Vault c'è il segreto resend_api_key: senza, nessun account inattivo viene avvisato e quindi nessuno viene eliminato (solo quelli mai confermati). Il testo dell'email si genera con node scripts/build-email-templates.mjs (supabase/email-templates/account-deletion-warning.sql, copiato nella migrazione 0028).

Prova sul progetto di sviluppo (transazione annullata alla fine, non lascia tracce):

This is the beginning of the README. Read the rest at the original. Read the full README ↗