laravel-tools

CLI interna per portare sui progetti Laravel un workflow simile a trellis-tools.

Il focus attuale del progetto e del lavoro in corso e' il flusso di sviluppo locale:

• definire il progetto
• preparare il repo locale
• avviare lo stack Docker
• inizializzare Laravel dentro lo stack in esecuzione

Stato del progetto

Questo progetto e' ancora un grosso work in progress. La release corrente di riferimento e' 2.2.0, ma la priorita' adesso resta stabilizzare il flusso locale e documentare bene le nuove funzionalita' prima di espandere il resto del tool.

Obiettivo

laravel-tools prende come benchmark @jumpgroup/trellis-tools, ma lo adatta a progetti Laravel che non usano Trellis.

Oggi i gruppi di comandi presenti sono:

• local
• database
• cache
• media (S3 + CloudFront)

Prerequisiti locali

Per testare seriamente il flusso locale su un progetto servono:

• Node.js >=20
• Docker Desktop con docker compose
• mkcert installato e inizializzato con mkcert -install
• permessi per usare sudo localmente
• file .env.example nel progetto Laravel target
• file .secret-fetcher nel progetto Laravel target

Dipendenze opzionali ma rilevanti:

• Google Drive configurato per i dump database
• laravel-tools.yml nel root del progetto target se vuoi usare i comandi remoti

Installazione sviluppo

Nel repo di laravel-tools:

npm install
npm link

Questo espone il comando laravel-tools in locale.

Quickstart locale

Dentro un progetto Laravel reale:

npx laravel-tools local setup-project
yarn repo-setup
yarn start
yarn setup-laravel

Con variante PHP esplicita:

npx laravel-tools local setup-project
laravel-tools local setup-repo --phpversion php8.2
yarn start
yarn setup-laravel

Se il boilerplate espone gia' yarn repo-setup, quello resta il percorso standard. Il comando manuale con --phpversion serve solo quando vuoi forzare una variante PHP diversa dal default nello step 2.

Cosa fa il flusso locale

local setup-project

Esegue questi passi:

1. controlla che .env.example esista
2. controlla che .secret-fetcher esista
3. legge APP_NAME da .env.example
4. chiede conferma o modifica del nome progetto
5. normalizza il nome in uno slug sicuro per host locali, container Docker e routing Traefik
6. aggiorna APP_NAME, APP_URL e ASSETS_URL in .env.example
7. opzionalmente configura lo stack media AWS (S3 + CloudFront), con default no

Questa fase definisce l'identita' del progetto.

Non fa:

• generazione di .env
• copia degli stub Docker
• generazione dei certificati
• modifica di /etc/hosts
• composer install
• avvio di Docker
• migration o seeder
• creazione risorse AWS, se scegli no al prompt media

Se scegli si al prompt media:

• usa il nome progetto normalizzato come identita' AWS del progetto
• prova a configurare o riconciliare bucket S3, CloudFront e IAM media
• aggiorna .env.example con i valori media risultanti
• invia le credenziali media a secret-fetcher se il progetto e' configurato

local setup-repo

Esegue questi passi:

1. controlla i prerequisiti minimi locali
2. legge .env.example e verifica che il progetto sia inizializzato
3. usa @jumpgroup/secret-fetcher per generare .env
4. copia gli stub Docker e Traefik nel progetto
5. genera i certificati locali con mkcert
6. aggiunge {APP_NAME}.test e mail.{APP_NAME}.test a /etc/hosts

Questa fase rende il checkout locale eseguibile sulla macchina.

Note importanti:

• gli stub Docker preferiscono DB_DATABASE
• per compatibilita' il tool accetta anche DB_NAME
• APP_NAME e' la singola fonte di naming e pilota:
  • https://{APP_NAME}.test
  • ${APP_NAME}-api
  • ${APP_NAME}-mysql
  • ${APP_NAME}-mailpit
• Traefik e' pensato per servire https://{APP_NAME}.test
• Mailpit e' esposto su https://mail.{APP_NAME}.test

local setup-laravel

Esegue questi passi:

1. verifica che .env esista
2. verifica che il container ${APP_NAME}-api sia in esecuzione
3. genera APP_KEY solo se manca
4. lancia le migration
5. opzionalmente esegue i seeder

Questa fase inizializza Laravel dentro lo stack gia' avviato.

local doctor

Esegue una diagnostica rapida del progetto locale e segnala:

1. file chiave presenti/mancanti (.env.example, .secret-fetcher, .env, docker-compose.yml, certificati)
2. variabili minime richieste in .env.example
3. prerequisiti locali (docker compose, mkcert, composer, sudo)
4. stato Docker daemon e container ${APP_NAME}-api / ${APP_NAME}-mysql

Il comando termina con errore se trova problemi bloccanti.

Checklist di validazione locale

Quando proviamo laravel-tools su un progetto reale, questa e' la checklist minima:

• npx laravel-tools local setup-project termina senza errori
• laravel-tools local setup-repo termina senza errori
• yarn start avvia correttamente traefik, api, db, mailpit
• laravel-tools local setup-laravel termina senza errori
• https://{APP_NAME}.test risponde
• https://mail.{APP_NAME}.test risponde
• i comandi database local-export e database local-import funzionano
• cache flush-local funziona

Stack media AWS

Il gruppo media gestisce lo stack media del progetto su AWS con questo modello:

• bucket S3 privato
• CloudFront davanti al bucket
• Origin Access Control (OAC) per l'accesso da CloudFront a S3
• bucket policy che consente lettura solo alla distribuzione CloudFront del progetto
• IAM user dedicato per upload, delete e invalidation applicative

Il naming e' deterministico:

• bucket: ${APP_NAME}-media
• OAC: ${APP_NAME}-media-oac
• IAM user: media-user.${APP_NAME}
• tag AWS usato per il matching: site=${APP_NAME}

Prerequisiti AWS

Per usare i comandi media servono:

• credenziali AWS locali valide nel profilo condiviso (AWS_PROFILE, default default)
• permessi per S3, CloudFront, IAM e STS nell'account target
• .env.example presente se vuoi usare il fallback automatico a APP_NAME

Regioni usate dal tool:

• S3: AWS_REGION oppure AWS_DEFAULT_REGION, fallback eu-central-1
• CloudFront/IAM/STS: us-east-1 salvo override di AWS_CLOUDFRONT_REGION

Comandi media

media setup-general

Esegue il setup completo dello stack media per il progetto corrente:

1. crea o riconcilia il bucket ${APP_NAME}-media
2. impone una configurazione privata al bucket
3. crea o riconcilia la distribuzione CloudFront del progetto
4. crea o riconcilia l'OAC usato dalla distribuzione
5. applica o aggiorna la bucket policy per consentire la lettura a CloudFront
6. crea o aggiorna lo IAM user dedicato al media
7. ruota le access key in modo safe
8. aggiorna .env.example
9. invia le credenziali a secret-fetcher se presente

Il comando e' pensato per essere rilanciabile senza dover distruggere le risorse esistenti.

media setup-iam

Crea o aggiorna solo lo IAM user media:

• cerca la distribuzione CloudFront del progetto tramite tag site
• aggiorna la policy inline dello user
• genera una nuova access key e rimuove quella vecchia solo dopo creazione riuscita

Questo comando e' utile quando vuoi rigenerare credenziali senza toccare bucket o CloudFront.

media s3 list

Lista i bucket S3 visibili al profilo AWS corrente, mostrando il tag site quando presente.

media s3 get --tag <tag>

Cerca bucket tramite tag site=<tag>. Se trova piu' bucket con lo stesso tag, apre una scelta interattiva.

media cloudfront list

Lista le distribuzioni CloudFront visibili al profilo AWS corrente, mostrando:

• ID
• ARN
• domain name
• status
• comment
• tag site

media cloudfront get --tag <tag>

Recupera la distribuzione CloudFront del progetto con match esatto sul tag site.

Se esistono piu' distribuzioni con lo stesso tag, il comando fallisce esplicitamente: non prova a indovinare.

media cloudfront setup

Crea o riconcilia la distribuzione CloudFront del progetto e garantisce che:

• il bucket esista gia'
• la distribuzione usi OAC
• la bucket policy permetta la lettura a quella distribuzione

Non crea lo IAM user: per quello serve media setup-general oppure media setup-iam.

Variabili .env.example aggiornate

Quando il setup media aggiorna .env.example, scrive:

• AWS_DEFAULT_REGION
• AWS_BUCKET
• AWS_URL
• CLOUDFRONT_DISTRIBUTION_ID
• CLOUDFRONT_DOMAIN
• S3_SITE_BUCKET
• S3_UPLOADS_BUCKET_URL

Esempi

laravel-tools media setup-general
laravel-tools media setup-general --name my-project
laravel-tools media setup-iam
laravel-tools media setup-iam --cloudfront E1234567890ABC
laravel-tools media s3 get --tag my-project
laravel-tools media cloudfront get --tag my-project
laravel-tools media cloudfront setup --name my-project

Comandi utili

npx laravel-tools local setup-project
laravel-tools local doctor
laravel-tools local setup-repo
laravel-tools local setup-repo --phpversion php8.4
laravel-tools local setup-laravel
laravel-tools media setup-general
laravel-tools media s3 list
laravel-tools media cloudfront list
laravel-tools cache flush-local
laravel-tools database local-export
laravel-tools database local-import

Configurazione remota

I comandi remoti leggono laravel-tools.yml dal root del progetto target:

staging:
  host: 1.2.3.4
  user: deployer

production:
  host: 5.6.7.8
  user: deployer

Workflow multi-repo con Codex

Per i task che coinvolgono piu' repository, il workflow raccomandato e' una singola sessione Codex centrata su laravel-tools, con:

• un repo secondario modificabile, per esempio il boilerplate Laravel
• un repo reale usato come riferimento read-only

Questo workflow non e' una feature del codice di laravel-tools: e' una convenzione operativa per lavorare piu' velocemente tra tool, boilerplate e progetto reale.

Struttura consigliata dei ruoli

• primary repo: laravel-tools
• secondary writable repo: boilerplate Laravel
• reference read-only repo: progetto Laravel reale

Comando base

codex -C /path/to/laravel-tools \
  --add-dir /path/to/laravel-boilerplate \
  --add-dir /path/to/laravel-real-project

Prompt iniziale standard

Workspace multi-repo:

- Primary repo: laravel-tools
- Secondary writable repo: laravel-boilerplate
- Reference read-only repo: laravel-real-project

Rules:
- Do not change any code without my approval.
- Ask approval separately for each repo before any patch.
- Use laravel-real-project only as reference unless I explicitly authorize changes there.

Current goal:
[descrizione task]

Ordine operativo per ogni task

1. esplorare laravel-tools
2. esplorare il boilerplate se il task tocca il flusso locale o gli stub
3. confrontare il progetto reale solo per validare struttura, naming, convenzioni o edge cases
4. proporre un piano di modifica separato per repo
5. aspettare approvazione esplicita
6. applicare cambi solo nel repo autorizzato

Regole decisionali

• laravel-tools contiene la logica CLI, i command group, i controlli e la documentazione del tool
• il boilerplate e' il target principale per verificare che setup-project, setup-repo, setup-laravel, Docker e convenzioni env funzionino davvero
• il progetto reale serve come benchmark di compatibilita' e riferimento architetturale
• nessun cambiamento cross-repo va fatto in un unico passaggio implicito
• se un task richiede modifiche in piu' repo, l'output va separato in blocchi: repo tools, repo boilerplate, repo reference
• il repo reale resta read-only di default

Checklist di validazione

• aprire una sessione unica con laravel-tools come root e gli altri repo come --add-dir
• eseguire un task di sola analisi cross-repo e verificare che i ruoli siano distinti correttamente
• eseguire un task che richiede cambi su laravel-tools e boilerplate e verificare che l'approvazione sia chiesta separatamente
• verificare che il repo reale venga trattato come read-only salvo override esplicito

Primo task consigliato

Usare il workflow multi-repo per:

• confrontare il flusso locale tra laravel-tools, boilerplate e progetto reale
• produrre una gap analysis
• proporre cambi solo su laravel-tools e boilerplate
• lasciare il progetto reale come benchmark

Direzione attuale

Le prossime iterazioni dovrebbero concentrarsi su:

• test end-to-end del flusso locale su un progetto Laravel reale
• applicazione del workflow multi-repo per confrontare tool, boilerplate e progetto reale
• rimozione delle incoerenze residue tra stub, documentazione e comportamento CLI
• solo dopo, nuove funzionalita' cross-repo o nuovi command group