@jumpgroup/laravel-tools 3.3.0

package/docs/releases/release_2.2.4.md

@@ -0,0 +1,75 @@
+# Release 2.2.4 — Prevenzione distribuzioni CloudFront duplicate e CDN lookup robusto
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+Tre fix correlati al layer CloudFront che prevengono la creazione di
+distribuzioni duplicate e rendono il lookup di quella esistente più
+robusto in caso di tag AWS temporaneamente non disponibili.
+
+---
+
+## Fixed
+
+- **Prevenzione duplicati CloudFront** (`getDistributionsByProjectTag`):
+  - Il metodo usava solo il tag `site` per identificare la distribuzione
+    del progetto; se il tag lookup falliva, restituiva zero risultati
+    e il tool procedeva a crearne una nuova
+  - Aggiunto fallback su `comment` (`CDN for {projectName}`) quando
+    nessun match esatto per tag viene trovato
+  - Se il fallback per comment trova risultati, stampa un avviso
+    `⚠️ Tag lookup unavailable/incomplete`
+  - Se il lookup fallisce completamente ma ci sono errori di tag listing,
+    ora lancia un errore esplicito invece di procedere silenziosamente
+
+- **CDN lookup deterministico** (`resolveOrCreateDistributionForProject`):
+  - Il lookup ora usa `getDistributionForProjectStrict` (nuova funzione)
+    che verifica sia tag/comment *sia* il dominio dell'origine S3,
+    riducendo drasticamente la probabilità di match ambigui o falsi
+  - La funzione supporta entrambi i formati di dominio S3
+    (regionale `bucket.s3.region.amazonaws.com` e globale
+    `bucket.s3.amazonaws.com`) tramite un set di candidati
+  - Se vengono trovate più distribuzioni candidate, stampa la tabella
+    e lancia un errore che richiede risoluzione manuale
+
+- **Fix aws-sdk `PutObjectCommand`**:
+  - Il `Body` della chiave cartella S3 era passato come stringa vuota `''`;
+    alcune versioni dell'SDK lo rifiutavano come tipo non valido
+  - Sostituito con `Buffer.alloc(0)` per garantire compatibilità
+
+---
+
+## Added
+
+- `getBucketOriginDomainCandidates()` in `src/aws/cloudfront.js`:
+  helper che restituisce un `Set` con i due possibili formati del dominio
+  S3 origin per un bucket (regionale + globale)
+
+- `getDistributionForProjectStrict()` in `src/aws/cloudfront.js`:
+  lookup deterministico che combina match su origin domain, comment e tag
+  con gestione esplicita dei casi ambigui (0 match → `null`,
+  1 match → oggetto, 2+ match → errore)
+
+- Campo `originDomainNames` nei row CloudFront restituiti da
+  `distributionToRow()`, per supportare il match sull'origin S3
+
+---
+
+## Files changed
+
+- `src/aws/cloudfront.js`
+- `src/aws/bucket.js`
+
+---
+
+## Impact
+
+- Eliminato il rischio di creare distribuzioni CloudFront duplicate su
+  account dove il tag listing è temporaneamente degradato
+- Il lookup della distribuzione esistente è ora vincolato all'origin S3
+  del progetto, rendendo l'idempotenza affidabile anche su account
+  con molte distribuzioni
+- Fix compatibilità aws-sdk per la creazione della cartella S3 iniziale

package/docs/releases/release_2.2.5.md

@@ -0,0 +1,69 @@
+# Release 2.2.5 — Laravel health check e recovery post-setup
+
+**Date:** 2026-04-23
+
+---
+
+## Overview
+
+Migliora la fase finale di `local setup-laravel` con un health check esplicito
+del bootstrap Laravel e un meccanismo di recovery automatico per i casi in cui
+l'applicazione non si avvia correttamente dopo il setup.
+
+Aggiunge anche una nuova utility `executeCommandWithOutput` che cattura stdout/stderr
+dai comandi Docker, rendendo gli errori diagnosticabili invece di opachi.
+
+---
+
+## Added
+
+- `executeCommandWithOutput` in `src/utilities/command.js`:
+  nuovo helper che esegue un comando con stdio in pipe, restituisce stdout in caso
+  di successo, e include stderr (o stdout come fallback) nel messaggio di errore in
+  caso di exit code non-zero
+
+- Health check Laravel post-setup tramite `php artisan about`:
+  verifica che il bootstrap dell'applicazione sia integro prima di procedere ai seeder
+
+- Recovery automatico senza Filament (`runNoFilamentRecovery`):
+  se il health check fallisce su un progetto senza Filament, esegue automaticamente
+  `composer install`, `package:discover`, `storage:link`, `optimize:clear` e ripete
+  il check; se fallisce di nuovo, lancia un errore con output artisan incluso
+
+- Log di conferma `✅ Bootstrap Laravel verificato.` (e variante `dopo recovery`)
+  al termine del health check riuscito
+
+---
+
+## Changed
+
+- `runLaravelHealthCheck` ora usa `executeCommandWithOutput` invece di `executeCommand`
+  con `stdio: pipe`: l'output di artisan è ora visibile nei messaggi di errore
+
+- `runNoFilamentRecovery` esegue ora anche `php artisan storage:link` tra
+  `package:discover` e `optimize:clear`, coprendo un caso comune di bootstrap rotto
+
+- Errore in caso di health check fallito con Filament installato:
+  ora è un messaggio in italiano con indicazioni operative e output artisan allegato,
+  invece di un re-throw grezzo dal processo executor
+
+- Errore in caso di recovery fallito (senza Filament):
+  ora include l'output artisan del secondo tentativo per facilitare la diagnosi
+
+---
+
+## Files changed
+
+- `src/utilities/command.js`
+- `src/local/setup.js`
+
+---
+
+## Impact
+
+- I fallimenti di bootstrap Laravel sono ora diagnosticabili: l'output di artisan
+  appare direttamente nel messaggio di errore invece di sparire nel pipe
+- Il recovery automatico riduce i casi in cui il developer deve rilanciareil setup
+  manualmente per progetti senza Filament
+- `storage:link` aggiunto al recovery copre un caso comune di Laravel che non trova
+  la cartella pubblica dei file

package/docs/releases/release_3.0.0.md

@@ -0,0 +1,87 @@
+# Release 3.0.0 — Gruppo comandi `forge`
+
+**Date:** 2026-04-23
+
+---
+
+## Overview
+
+Introduce il gruppo comandi `forge`: integrazione diretta con Laravel Forge via API,
+senza dipendenze PHP. Permette di gestire deploy, variabili d'ambiente e log
+direttamente dal terminale, su qualsiasi progetto Laravel gestito da Forge.
+
+L'integrazione punta alla nuova API Forge (`/api`), evitando deliberatamente
+la versione legacy `/api/v1` deprecata e prevista per la dismissione il 30 giugno 2026.
+
+---
+
+## Added
+
+### Comandi
+
+| Comando | Descrizione |
+|---|---|
+| `forge token set` | Salva il token Forge API in `~/.laravel-tools` |
+| `forge servers` | Elenca tutti i server dell'account Forge |
+| `forge deploy` | Seleziona server → sito → avvia deploy |
+| `forge env get` | Seleziona server → sito → stampa il `.env` remoto |
+| `forge env set` | Seleziona server → sito → sovrascrive il `.env` remoto |
+| `forge logs` | Seleziona server → sito → stampa il log dell'ultimo deploy |
+
+### Moduli
+
+- `src/forge/config.js` — lettura/scrittura `~/.laravel-tools` (JSON globale per credenziali);
+  errore esplicito in italiano se il token non è configurato
+
+- `src/forge/client.js` — wrapper `fetch` verso `https://forge.laravel.com/api`;
+  mapping completo degli errori HTTP (401, 403, 404, 422, 429) in messaggi italiani
+
+- `src/forge/servers.js` — `listServers()` e `pickServer()` interattivo via `@inquirer/select`
+
+- `src/forge/sites.js` — `listSites()`, `pickSite()`, `deploySite()`, `getEnv()`, `setEnv()`,
+  `getDeploymentLog()` e prompt di conferma distruttiva per `env set`
+
+- `bin/groups/forge.js` — wiring Commander per tutti i comandi del gruppo
+
+---
+
+## Design decisions
+
+- **Token globale in `~/.laravel-tools`**: il token Forge è per account, non per progetto.
+  Viene salvato una sola volta sulla macchina del developer e riutilizzato su tutti i progetti.
+
+- **Server/sito sempre interattivi**: il tool è usato su progetti diversi ogni volta,
+  quindi non ha senso memorizzare IDs in `laravel-tools.yml`.
+
+- **Nessuna dipendenza aggiuntiva**: il client HTTP usa `fetch` nativo (Node 20+,
+  già requisito del progetto). Nessun package npm aggiunto.
+
+- **Nuova API Forge (`/api`)**: la versione legacy `/api/v1` è deprecata.
+  Partire dalla nuova API evita una migrazione forzata entro giugno 2026.
+
+- **`forge env set` è distruttivo**: sovrascrive completamente il `.env` remoto.
+  Il prompt di conferma è esplicito e in rosso:
+  `DISTRUTTIVO: Se confermi l'env remote verrà sovrascritto! Sicuro di voler continuare?`
+
+---
+
+## Files changed
+
+- `src/forge/config.js` (nuovo)
+- `src/forge/client.js` (nuovo)
+- `src/forge/servers.js` (nuovo)
+- `src/forge/sites.js` (nuovo)
+- `bin/groups/forge.js` (nuovo)
+- `bin/tools.js`
+- `package.json`
+
+---
+
+## Impact
+
+- I developer possono avviare deploy, leggere log e gestire variabili d'ambiente
+  Forge direttamente dal terminale senza aprire la UI web
+- Nessuna dipendenza dal package PHP `laravel/forge-sdk`: l'integrazione è
+  implementata nativamente in Node.js
+- L'architettura è predisposta per aggiungere nuovi comandi Forge senza toccare
+  il client o la configurazione

package/docs/releases/release_3.0.1.md

@@ -0,0 +1,65 @@
+# Release 3.0.1 — Fix server path per Forge su AWS
+
+**Date:** 2026-04-23
+
+---
+
+## Overview
+
+Corregge il path remoto usato dai comandi `database remote-export`,
+`database remote-import` e `cache flush-remote`.
+
+Il path precedente (`/var/www/{APP_NAME}/current`) era derivato dalla
+convenzione Deployer e non corrisponde alla struttura reale dei server
+gestiti da Laravel Forge, dove il path è basato sul dominio del sito
+(es. `/home/forge/api.goego.it`).
+
+---
+
+## Fixed
+
+- `getServerPath` non deriva più il path dall'`APP_NAME`: legge ora
+  il campo `path` da `laravel-tools.yml` per l'ambiente selezionato
+- Se `path` non è configurato, lancia un errore esplicito con esempio
+  di configurazione
+- `cache flush-remote` passava `appName` a `getServerPath` invece
+  di `env` — corretto
+
+---
+
+## Changed
+
+- `getServerPath` spostato da `src/utilities/pathUtils.js` a
+  `src/utilities/command.js`, dove vivono già `getIp` e `getSshUser`
+  (stessa fonte di configurazione: `laravel-tools.yml`)
+- `src/database.js` e `src/cache.js` aggiornati per importare
+  `getServerPath` da `command.js`
+
+---
+
+## Migration
+
+Aggiungere `path` a ogni ambiente in `laravel-tools.yml`:
+
+```yaml
+staging:
+  host: 1.2.3.4
+  user: forge
+  path: /home/forge/staging.your-site.com
+production:
+  host: 5.6.7.8
+  user: forge
+  path: /home/forge/your-site.com
+```
+
+Il valore di `path` corrisponde al nome della directory del sito
+visibile in **Forge → Server → Sites**.
+
+---
+
+## Files changed
+
+- `src/utilities/command.js`
+- `src/utilities/pathUtils.js`
+- `src/database.js`
+- `src/cache.js`

package/docs/releases/release_3.1.0.md

@@ -0,0 +1,90 @@
+# Release 3.1.0 — `forge server create`
+
+**Date:** 2026-04-24
+
+---
+
+## Overview
+
+Aggiunge il comando `forge server create` per provisionare un nuovo server
+AWS Lightsail tramite Forge API direttamente dal terminale.
+
+Il comando supporta il pattern blue/green usato in azienda: quando esiste già
+un server con lo stesso nome, auto-incrementa il suffisso (`myapp-staging` →
+`myapp-staging-2` → `myapp-staging-3`) e chiede conferma prima di procedere.
+Il passaggio dell'IP statico tra le istanze rimane manuale via AWS Console.
+
+---
+
+## Added
+
+### Comando
+
+```bash
+laravel-tools forge server create
+```
+
+### Flusso interattivo
+
+1. Recupero automatico credenziale AWS da Forge (nessuna configurazione aggiuntiva)
+2. Lettura versione PHP da `composer.json` → conversione al formato Forge (`php84` ecc.)
+3. Lettura `APP_NAME` da `.env.example`
+4. Selezione ambiente (`staging` / `production`) → nome base derivato (`{APP_NAME}-{env}`)
+5. Risoluzione nome con auto-incremento se il nome esiste già su Forge
+6. Conferma nome server prima di procedere
+7. Selezione regione AWS (`eu-central-1` / `us-west-2`)
+8. Recupero piani Lightsail disponibili via Forge API (fallback su lista standard se l'API non risponde)
+9. Selezione piano (nano / micro / small / medium / large / xlarge)
+10. Opzione Redis (default: no)
+11. Creazione server → polling ogni 20s fino a provisioning completo (timeout 25 min)
+12. Output: nome, IP, PHP, Redis, hint passo successivo
+
+### Logica di naming per blue/green
+
+| Servers esistenti | Nome assegnato |
+|---|---|
+| nessuno | `myapp-staging` |
+| `myapp-staging` | `myapp-staging-2` |
+| `myapp-staging`, `myapp-staging-2` | `myapp-staging-3` |
+
+Il workflow aziendale prevede: spin up nuovo server → swap IP statico Lightsail
+(manuale via AWS Console) → backup → delete del server precedente.
+
+### Parametri server fissi
+
+| Parametro | Valore |
+|---|---|
+| Provider | `aws` |
+| Tipo | `app` |
+| Database | MySQL 8 (`mysql8`) |
+| Ubuntu | 24.04 |
+
+### Nuovo modulo
+
+- `src/forge/provisioning.js`:
+  - `getAwsCredential()` — trova la credenziale AWS nell'account Forge
+  - `getSizesForRegion()` — recupera i piani Lightsail via API con fallback
+  - `readPhpVersionFromComposer()` — legge e converte la versione PHP
+  - `readAppName()` — legge `APP_NAME` da `.env.example`
+  - `resolveServerName()` — auto-incrementa il nome se già in uso
+  - `promptServerConfig()` — flusso interattivo completo
+  - `createServer()` — chiama `POST /servers`
+  - `pollServerReady()` — polling con progress dots fino a `is_ready`
+
+---
+
+## Files changed
+
+- `src/forge/provisioning.js` (nuovo)
+- `bin/groups/forge.js`
+
+---
+
+## Impact
+
+- Il provisioning di un nuovo server staging/production richiede ora
+  un solo comando invece di navigare la UI Forge
+- Il pattern blue/green è gestito nativamente: nessun rischio di sovrascrivere
+  un server esistente per errore di naming
+- La versione PHP viene letta dal progetto reale, eliminando il rischio
+  di disallineamento tra ambiente locale e server remoto

package/docs/releases/release_3.2.0.md

@@ -0,0 +1,74 @@
+# Release 3.2.0 — `forge site create`
+
+**Date:** 2026-04-24
+
+---
+
+## Overview
+
+Aggiunge il comando `forge site create` per collegare un sito Laravel
+a un server Forge esistente e installare il repository Git in un unico flusso.
+
+Insieme a `forge server create` (3.1.0), copre i due passi fondamentali
+del provisioning di un nuovo ambiente staging/production:
+
+```
+forge server create   →   forge site create   →   forge env set   →   forge deploy
+```
+
+---
+
+## Added
+
+### Comando
+
+```bash
+laravel-tools forge site create
+```
+
+### Flusso interattivo
+
+1. Lettura PHP version da `composer.json` (stesso meccanismo di `forge server create`)
+2. Lettura `APP_NAME` da `.env.example` → suggerisce nome database (`app_name`)
+3. Selezione server esistente su Forge
+4. Input dominio del sito (es. `staging.myapp.com`)
+5. Input nome database (default: `APP_NAME` con trattini → underscore)
+6. Selezione provider Git (GitHub / GitLab / Bitbucket)
+7. Input repository in formato `org/repo`
+8. Input branch (default: `main`)
+9. Creazione sito via API → polling ogni 5s fino a `status=installed` (timeout 5 min)
+10. Installazione repository Git + `composer install` automatico
+11. Output riepilogo + hint passi successivi (`forge env set` → `forge deploy`)
+
+### Parametri sito fissi
+
+| Parametro | Valore |
+|---|---|
+| Tipo progetto | `php` |
+| Web directory | `/public` |
+| PHP version | letta da `composer.json` |
+| Composer install | `true` |
+
+### Nuove funzioni in `src/forge/sites.js`
+
+- `createSite(serverId, payload)` — chiama `POST /servers/{id}/sites`
+- `pollSiteInstalled(serverId, siteId)` — polling ogni 5s fino a `status=installed`
+- `installGitRepo(serverId, siteId, payload)` — chiama `POST /servers/{id}/sites/{id}/git`
+
+---
+
+## Files changed
+
+- `src/forge/sites.js`
+- `bin/groups/forge.js`
+
+---
+
+## Impact
+
+- Il setup di un nuovo sito su un server Forge esistente richiede ora
+  un solo comando guidato invece di navigare la UI
+- Il repository Git viene collegato e `composer install` eseguito
+  automaticamente al termine della creazione del sito
+- Il flusso `server create` → `site create` → `env set` → `deploy`
+  copre ora l'intero ciclo di provisioning di un nuovo ambiente

package/docs/releases/release_3.3.0.md

@@ -0,0 +1,72 @@
+# Release 3.3.0 — `forge server delete` + convenzione domini
+
+**Date:** 2026-04-24
+
+---
+
+## Overview
+
+Aggiunge `forge server delete` per eliminare un server Forge dalla CLI,
+introduce la convenzione domini con prefisso `api.` in tutti gli ambienti,
+e corregge un crash in `forge site create`.
+
+---
+
+## Added
+
+### `forge server delete`
+
+```bash
+laravel-tools forge server delete
+```
+
+- Mostra lista server → selezione interattiva
+- Avviso in rosso con nome e IP del server da eliminare
+- Conferma distruttiva con default `N`
+- Chiama `DELETE /servers/{id}` via Forge API
+
+> Nota: Forge tenta di terminare anche l'istanza EC2 sottostante, ma può fallire silenziosamente se le credenziali AWS su Forge non hanno il permesso `ec2:TerminateInstances`. In quel caso, terminare l'istanza manualmente dalla console AWS o via `aws ec2 terminate-instances`.
+
+---
+
+## Changed
+
+### Convenzione domini — prefisso `api.`
+
+Tutti i progetti Laravel creati con laravel-tools seguono ora la convenzione:
+
+| Ambiente   | Dominio                          |
+|------------|----------------------------------|
+| Locale     | `api.{appName}.test`             |
+| Staging    | `api.{appName}.sitointest.it`    |
+| Production | `api.{appName}.it`               |
+
+#### Locale (`local setup-repo`)
+
+- Certificati SSL generati per `api.{appName}.test` (era `{appName}.test`)
+- `/etc/hosts` aggiornato con `api.{appName}.test`
+- `APP_URL` e `ASSETS_URL` in `.env.example` impostati a `https://api.{appName}.test`
+
+#### Forge (`forge site create`)
+
+- Il campo dominio si pre-compila automaticamente:
+  - Server con "staging" nel nome → `api.{appName}.sitointest.it`
+  - Server production → `api.{appName}.it`
+- L'utente può modificare il valore prima di confermare
+
+---
+
+## Fixed
+
+- Import mancante di `select` in `bin/groups/forge.js`: causava
+  `ReferenceError: select is not defined` durante `forge site create`
+  al passo di selezione del provider Git (GitHub/GitLab/Bitbucket)
+
+---
+
+## Files changed
+
+- `src/forge/servers.js` — aggiunto `deleteServer(serverId)`
+- `src/local/setup.js` — convenzione `api.` per dominio locale
+- `bin/groups/forge.js` — comando `server delete`, default dominio `forge site create`, fix import `select`
+- `package.json` — versione `3.3.0`

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jumpgroup/laravel-tools",
+  "version": "3.3.0",
+  "description": "CLI tool for managing the full lifecycle of Laravel projects at JumpGroup",
+  "type": "module",
+  "bin": {
+    "laravel-tools": "bin/tools.js"
+  },
+  "scripts": {
+    "start": "node bin/tools.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-cloudfront": "^3.924.0",
+    "@aws-sdk/client-iam": "^3.924.0",
+    "@aws-sdk/client-s3": "^3.924.0",
+    "@aws-sdk/client-sts": "^3.924.0",
+    "@aws-sdk/credential-provider-ini": "^3.924.0",
+    "@inquirer/prompts": "^1.1.3",
+    "@inquirer/select": "^1.2.6",
+    "@jumpgroup/secret-fetcher": "^2.1.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^10.0.0",
+    "dotenv": "^16.0.0",
+    "glob": "^10.2.2",
+    "hostile": "^1.3.3",
+    "js-yaml": "^4.1.0",
+    "keytar": "^7.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}