@jumpgroup/laravel-tools 3.3.0

package/.claude/settings.local.json

@@ -0,0 +1,59 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude-buddy__buddy_show",
+      "mcp__claude-buddy__buddy_pet",
+      "mcp__serena__write_memory",
+      "mcp__serena__check_onboarding_performed",
+      "mcp__serena__initial_instructions",
+      "Skill(update-config)",
+      "Bash(npx --yes sequential-thinking --version)",
+      "Read(//Users/andre/.npm/**)",
+      "Read(//usr/local/bin/**)",
+      "Read(//Users/andre/.claude/**)",
+      "Read(//Users/andre/.config/claude/**)",
+      "Read(//Users/andre/.config/**)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "agent",
+            "prompt": "A file was just edited. Tool input: $ARGUMENTS. Using Serena tools (get_symbols_overview, find_symbol, find_referencing_symbols), briefly validate the changed file: check for symbol correctness, broken references, and consistency with the codebase. Report only real issues. If everything looks fine, output nothing.",
+            "statusMessage": "sc:reflect — validating changes...",
+            "timeout": 30,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "agent",
+            "prompt": "A git commit command is about to run. Command: $ARGUMENTS. Using Serena tools, analyze the codebase for critical issues that should block this commit: security vulnerabilities, broken symbol references, obvious bugs. If critical issues are found, set permissionDecision to deny with a clear explanation. If only minor or no issues, allow the commit.",
+            "if": "Bash(git commit*)",
+            "statusMessage": "sc:analyze — pre-commit review...",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '{\"systemMessage\":\"sc:load: Read Serena project memories (code_style, codebase_structure, project_overview, suggested_commands, tech_stack) via mcp__serena__read_memory to restore full project context before your first response.\"}'",
+            "statusMessage": "sc:load — restoring context..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,378 @@
+# 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`:
+
+```bash
+npm install
+npm link
+```
+
+Questo espone il comando `laravel-tools` in locale.
+
+## Quickstart locale
+
+Dentro un progetto Laravel reale:
+
+```bash
+npx laravel-tools local setup-project
+yarn repo-setup
+yarn start
+yarn setup-laravel
+```
+
+Con variante PHP esplicita:
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:
+
+```yaml
+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
+
+```bash
+codex -C /path/to/laravel-tools \
+  --add-dir /path/to/laravel-boilerplate \
+  --add-dir /path/to/laravel-real-project
+```
+
+### Prompt iniziale standard
+
+```text
+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

package/bin/groups/cache.js

@@ -0,0 +1,52 @@
+import { Option } from 'commander';
+import { flushLocal, flushRemote, flushAll } from '../../src/cache.js';
+
+export default (program) => {
+  const cache = program.command('cache').description('Cache operations');
+
+  cache
+    .command('flush-local')
+    .description('Clear all Laravel caches in the local Docker environment')
+    .action(async () => {
+      try {
+        await flushLocal();
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  cache
+    .command('flush-remote')
+    .description('Clear all Laravel caches on a remote server')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment')
+        .choices(['staging', 'production'])
+        .default('staging')
+    )
+    .action(async (options) => {
+      try {
+        await flushRemote(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  cache
+    .command('flush-all')
+    .description('Clear all Laravel caches both locally and on a remote server')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment')
+        .choices(['staging', 'production'])
+        .default('staging')
+    )
+    .action(async (options) => {
+      try {
+        await flushAll(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+};

package/bin/groups/database.js

@@ -0,0 +1,105 @@
+import { Option } from 'commander';
+import {
+  remoteDownload,
+  dbLocalImport,
+  dbLocalExport,
+  remoteImport,
+  listDatabases,
+} from '../../src/database.js';
+
+export default (program) => {
+  const database = program
+    .command('database')
+    .description('Database operations');
+
+  database
+    .command('remote-export')
+    .description('Export database from remote server and download locally')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment')
+        .choices(['staging', 'production'])
+        .default('staging')
+    )
+    .addOption(new Option('-n, --name [name]', 'Custom filename'))
+    .addOption(new Option('--ams', 'AMS mode').default(false))
+    .addOption(new Option('--dry-run', 'Preview actions without executing').default(false))
+    .action(async (options) => {
+      try {
+        await remoteDownload(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  database
+    .command('local-import')
+    .description('Import a database dump into the local Docker environment')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment')
+        .choices(['staging', 'production'])
+        .default('staging')
+    )
+    .addOption(new Option('--ams', 'AMS mode').default(false))
+    .addOption(new Option('--dry-run', 'Preview actions without executing').default(false))
+    .action(async (options) => {
+      try {
+        await dbLocalImport(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  database
+    .command('local-export')
+    .description('Export database from the local Docker environment')
+    .addOption(new Option('-n, --name [name]', 'Custom filename'))
+    .addOption(new Option('--ams', 'AMS mode').default(false))
+    .addOption(new Option('--dry-run', 'Preview actions without executing').default(false))
+    .action(async (options) => {
+      try {
+        await dbLocalExport(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  database
+    .command('remote-import')
+    .description('Upload and import a database dump to a remote server')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment')
+        .choices(['staging', 'production'])
+        .default('staging')
+    )
+    .addOption(new Option('--ams', 'AMS mode').default(false))
+    .addOption(new Option('--dry-run', 'Preview actions without executing').default(false))
+    .action(async (options) => {
+      try {
+        await remoteImport(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+
+  database
+    .command('list')
+    .description('List available local database dumps')
+    .addOption(
+      new Option('-e, --environment [environment]', 'Environment').choices([
+        'staging',
+        'production',
+      ])
+    )
+    .action(async (options) => {
+      try {
+        await listDatabases(options);
+      } catch (error) {
+        console.error('❌ Error:', error.message);
+        process.exit(1);
+      }
+    });
+};