@jumpgroup/laravel-tools 3.3.0

package/docs/releases/release_2.0.0.md

@@ -0,0 +1,192 @@
+# Release 2.0.0 — AWS media stack (S3 + CloudFront)
+
+**Date:** 2026-04-07
+
+---
+
+## Overview
+
+Adds a new `media` command group focused on project media delivery through AWS.
+The feature is designed around a private S3 bucket fronted by CloudFront, with
+an Origin Access Control (OAC) and a dedicated IAM user for application uploads.
+
+This is not a generic AWS provisioning layer. It is a project-scoped media setup
+flow that assumes one logical media bucket and one logical CloudFront
+distribution per Laravel project, both identified by the `site` tag.
+
+---
+
+## Commands added
+
+| Command | What it does |
+|---------|-------------|
+| `media setup-general` | Full setup/reconcile flow: bucket, CloudFront, bucket policy, IAM user, env updates |
+| `media setup-iam` | Creates or rotates the project media IAM user credentials |
+| `media s3 list` | Lists S3 buckets and their `site` tag |
+| `media s3 get --tag <tag>` | Finds S3 bucket(s) by exact `site` tag |
+| `media cloudfront list` | Lists CloudFront distributions and their `site` tag |
+| `media cloudfront get --tag <tag>` | Finds the CloudFront distribution by exact `site` tag |
+| `media cloudfront setup` | Creates or reconciles the CloudFront distribution for a project and ensures S3 read access |
+
+---
+
+## Architecture
+
+The media stack now follows this model:
+
+- S3 bucket: private
+- Bucket ownership: `BucketOwnerEnforced`
+- Public access block: fully enabled
+- CloudFront origin: S3 REST endpoint
+- Access model: CloudFront OAC with SigV4 signing
+- Bucket policy: grants `s3:GetObject` only to the specific CloudFront distribution
+- Application credentials: dedicated IAM user per project
+
+This avoids the previous ambiguous middle ground between a public bucket and a
+private bucket. Uploaded objects are expected to stay private in S3 and be read
+through CloudFront.
+
+---
+
+## Files added
+
+### `bin/groups/media.js`
+CLI-only layer for the new `media` command group.
+
+Subcommands:
+- `setup-general`
+- `setup-iam`
+- `s3 list`
+- `s3 get`
+- `cloudfront list`
+- `cloudfront get`
+- `cloudfront setup`
+
+### `src/aws/config.js`
+AWS runtime configuration helpers:
+- profile resolution from `AWS_PROFILE` (fallback: `default`)
+- region resolution from `AWS_REGION` / `AWS_DEFAULT_REGION` (fallback: `eu-central-1`)
+- CloudFront region resolution (fallback: `us-east-1`)
+- credentials loading through the shared AWS config/credentials file
+- AWS account ID lookup through STS `GetCallerIdentity`
+
+### `src/aws/bucket.js`
+S3-specific media logic:
+- bucket creation for `${projectName}-media`
+- bucket existence checks
+- tagging via `site=<projectName>`
+- enforcement of private bucket posture
+- bucket listing / lookup helpers
+- merge-safe CloudFront bucket policy application
+
+`applyCloudFrontReadPolicy(...)` is intentionally idempotent:
+- reads the current bucket policy if present
+- removes only the statement for the same distribution
+- preserves unrelated statements
+- writes the merged result back
+
+### `src/aws/cloudfront.js`
+CloudFront-specific media logic:
+- distribution listing with tag resolution
+- strict lookup by exact `site` tag
+- OAC discovery/creation
+- distribution creation for the project bucket
+- reconciliation of existing distributions so the expected bucket origin uses OAC
+- standalone `cloudfront setup` flow that also ensures the S3 bucket read policy exists
+
+Important constraint:
+- distribution lookup is now strict by `site` tag
+- if multiple distributions share the same tag, the command fails and requires manual cleanup
+
+### `src/aws/iam.js`
+IAM-specific media logic:
+- ensures the project media user exists
+- writes/updates the inline media policy
+- tags the user with `site=<projectName>`
+- rotates access keys safely
+
+Safe key rotation behavior:
+- if 0 keys exist: create one
+- if 1 key exists: create the new key first, then delete the old one
+- if 2 keys exist: fail safely and require manual intervention
+
+### `src/media.js`
+Orchestration layer for the higher-level flows:
+
+**`setupMediaStack(projectName, options)`**
+1. creates or reconciles the S3 bucket
+2. creates or reconciles the CloudFront distribution
+3. applies the CloudFront-specific S3 bucket policy
+4. creates/rotates IAM credentials
+5. updates `.env.example`
+6. pushes credentials to `secret-fetcher` if configured
+
+**`setupMediaIam(projectName, cloudfrontId)`**
+1. resolves the distribution by project tag when needed
+2. creates/rotates the media IAM user
+3. pushes credentials to `secret-fetcher` if configured
+
+---
+
+## Integration with local setup
+
+`local setup-project` now asks whether the AWS media stack should also be configured.
+
+If confirmed, the command:
+- uses the normalized project name
+- launches `setupMediaStack(...)`
+- updates `.env.example` with the resulting media values
+
+If skipped, the media stack can be configured later with:
+
+```bash
+laravel-tools media setup-general
+```
+
+---
+
+## Environment variables written
+
+When media setup runs with env updates enabled, `.env.example` is enriched with:
+
+```env
+AWS_DEFAULT_REGION=
+AWS_BUCKET=
+AWS_URL=
+CLOUDFRONT_DISTRIBUTION_ID=
+CLOUDFRONT_DOMAIN=
+S3_SITE_BUCKET=
+S3_UPLOADS_BUCKET_URL=
+```
+
+These values are derived from the actual AWS resources created or resolved by
+the tool.
+
+---
+
+## Secret fetcher integration
+
+If `.secret-fetcher` exists in the target project root, the generated media IAM
+credentials are pushed through `@jumpgroup/secret-fetcher` under `env=site`.
+
+This allows the AWS access key pair to join the project's existing secret flow
+instead of remaining only in terminal output.
+
+---
+
+## Operational notes
+
+- The tool assumes valid local AWS credentials already exist in the shared AWS profile files.
+- S3 bucket naming is deterministic: `${APP_NAME}-media`.
+- CloudFront resources are matched by exact `site` tag, not by fuzzy name/domain heuristics.
+- `media cloudfront setup` requires the bucket to exist first.
+- The implementation is designed to be rerunnable without recreating resources unnecessarily.
+
+---
+
+## Impact
+
+- Laravel projects now have a first-party media setup path inside `laravel-tools`
+- The local project bootstrap can optionally provision media infrastructure during setup
+- The storage/CDN model is now documented and consistent:
+  private S3 + CloudFront OAC + dedicated media IAM user

package/docs/releases/release_2.0.1.md

@@ -0,0 +1,53 @@
+# Release 2.0.1 — Dry-run fix for S3 bucket policy setup
+
+**Date:** 2026-04-07
+
+---
+
+## Overview
+
+Hotfix release for the new AWS media stack introduced in `2.0.0`.
+
+The initial media implementation included dry-run support, but one path in the
+S3 bucket policy setup still performed real AWS-side read logic before exiting.
+That weakened the guarantee that a dry-run should be non-invasive.
+
+`2.0.1` fixes that behavior.
+
+---
+
+## Fixed
+
+- `applyCloudFrontReadPolicy(...)` now short-circuits immediately when `dryRun`
+  is enabled
+- the dry-run log message is emitted before any bucket policy read/merge logic
+- media dry-runs no longer attempt to inspect or update the current S3 bucket
+  policy while simulating CloudFront read access setup
+
+---
+
+## Files changed
+
+### `src/aws/bucket.js`
+The dry-run branch for CloudFront bucket policy application was moved earlier in
+the function.
+
+Before this fix:
+- the function still built the S3 client
+- resolved policy data
+- and reached real bucket-policy handling code before returning
+
+After this fix:
+- the function detects `dryRun` up front
+- prints the dry-run message
+- returns immediately without entering the AWS policy read/write path
+
+---
+
+## Impact
+
+- `media` dry-runs are more trustworthy
+- developers can simulate media stack reconciliation without touching bucket
+  policy state
+- the dry-run contract is now more consistent with the rest of the AWS setup flow
+

package/docs/releases/release_2.0.2.md

@@ -0,0 +1,55 @@
+# Release 2.0.2 — Dry-run fix for IAM access key setup
+
+**Date:** 2026-04-07
+
+---
+
+## Overview
+
+Second hotfix on top of the AWS media stack rollout.
+
+After `2.0.1`, one more dry-run inconsistency remained in the IAM credential
+flow: when the target media user did not exist yet, the dry-run path could
+still drift into real access-key listing assumptions.
+
+`2.0.2` fixes that edge case so IAM dry-runs behave coherently for both:
+- existing media users
+- brand-new media users
+
+---
+
+## Fixed
+
+- dry-run credential rotation now handles the "user does not exist yet" case explicitly
+- the IAM flow now returns deterministic placeholder access key values for a
+  brand-new user during dry-run
+- unnecessary dependency on real `ListAccessKeys` behavior was removed from
+  that creation path
+
+---
+
+## Files changed
+
+### `src/aws/iam.js`
+`rotateAccessKeysSafely(...)` now accepts the caller's knowledge about whether
+the IAM user already exists.
+
+Behavior after the fix:
+- if `dryRun` is enabled and the user does not exist yet:
+  - no real key listing is attempted
+  - placeholder credentials are returned immediately
+- if `dryRun` is enabled and the user already exists:
+  - the existing dry-run-safe rotation logic still applies
+
+The higher-level IAM setup flow now passes `userExists` into the rotation
+function so the dry-run branch can make the correct decision.
+
+---
+
+## Impact
+
+- `media setup-iam` dry-runs are now stable for first-time project setup
+- full media stack dry-runs produce predictable credential output even before
+  the IAM user exists
+- the AWS dry-run story is more internally consistent across S3 and IAM paths
+

package/docs/releases/release_2.0.3.md

@@ -0,0 +1,69 @@
+# Release 2.0.3 — Reduced AWS API usage in dry-run mode
+
+**Date:** 2026-04-07
+
+---
+
+## Overview
+
+Third hotfix after the AWS media stack rollout.
+
+The previous dry-run fixes made the media flow safer, but some preview paths
+were still performing avoidable AWS read operations before switching into
+simulation mode.
+
+`2.0.3` tightens that behavior further so dry-runs stay closer to the intended
+"preview only" contract and consume fewer AWS API calls.
+
+---
+
+## Changed
+
+- dry-run distribution setup now bypasses strict CloudFront lookup against the
+  live account
+- dry-run IAM setup now avoids resolving the real CloudFront distribution when
+  no explicit ID is provided
+- a deterministic simulated CloudFront ID is generated for dry-run IAM flows
+  that still need a distribution identifier
+
+---
+
+## Files changed
+
+### `src/aws/cloudfront.js`
+`resolveOrCreateDistributionForProject(...)` now checks `dryRun` before trying
+to find an existing tagged distribution.
+
+Behavior after the change:
+- if `dryRun` is enabled:
+  - the function goes directly through the simulated distribution creation path
+  - no strict CloudFront lookup is performed first
+- if `dryRun` is disabled:
+  - existing behavior remains unchanged
+  - real distribution lookup/reconciliation still happens
+
+### `src/media.js`
+The IAM setup flow now treats dry-run as a first-class branch when no
+CloudFront ID was passed.
+
+Behavior after the change:
+- non-dry-run:
+  - resolve the real CloudFront distribution by project tag as before
+- dry-run:
+  - skip the real lookup
+  - synthesize a predictable ID in the form `DRYRUN-{projectName}`
+  - continue the credential simulation flow using that placeholder
+
+This keeps dry-run output deterministic without requiring extra AWS reads.
+
+---
+
+## Impact
+
+- media dry-runs make fewer AWS API calls
+- preview flows are faster and less noisy
+- dry-run behavior is more consistent across:
+  - distribution setup
+  - bucket policy simulation
+  - IAM credential simulation
+

package/docs/releases/release_2.1.0.md

@@ -0,0 +1,59 @@
+# Release 2.1.0 — Database hardening and safer remote import
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+This release improves reliability and operator safety in the `database` command
+group, especially for remote import workflows.
+
+The focus is practical hardening:
+- safer execution flow for remote imports
+- dry-run preview support across database operations
+- clearer failure handling and rollback guidance
+
+---
+
+## Added
+
+- `--dry-run` support for:
+  - `database remote-export`
+  - `database local-import`
+  - `database local-export`
+  - `database remote-import`
+
+Dry-run now prints the commands that would run and avoids mutating local/remote
+database state.
+
+---
+
+## Remote import safety improvements
+
+`database remote-import` now includes explicit safety rails:
+
+- confirmation prompt before executing the remote import
+- prompt asking whether to create a pre-import backup of the remote database
+- automatic rollback command hint when import fails and backup exists
+- post-import health check (`SELECT 1`) on remote database
+- remote temporary dump cleanup only after successful import flow
+
+This reduces the chance of destructive mistakes and gives a clear recovery path
+for less experienced operators.
+
+---
+
+## Files changed
+
+- `bin/groups/database.js`
+- `src/database.js`
+
+---
+
+## Impact
+
+- safer remote DB operations for day-to-day team usage
+- better preview capability before running critical commands
+- clearer incident handling path on failed remote imports
+

package/docs/releases/release_2.2.0.md

@@ -0,0 +1,83 @@
+# Release 2.2.0 — `local doctor` diagnostics command
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+Adds `local doctor`, a fast diagnostics command designed to help teammates
+quickly understand why a local Laravel setup is not ready.
+
+The command provides a structured report with actionable pass/warn/fail checks
+instead of failing late inside setup commands.
+
+---
+
+## Added
+
+- New command:
+
+```bash
+laravel-tools local doctor
+```
+
+- CLI wiring in local command group
+- README usage and behavior documentation
+
+---
+
+## What `local doctor` checks
+
+1. Key project files:
+   - `.env.example`
+   - `.secret-fetcher`
+   - `.env`
+   - `docker-compose.yml`
+   - `docker/certs/site.test.pem`
+   - `docker/certs/site.key`
+   - `laravel-tools.yml`
+
+2. Minimal `.env.example` required keys:
+   - `APP_NAME`
+   - `APP_URL`
+   - `ASSETS_URL`
+   - `DB_DATABASE` or `DB_NAME`
+   - `DB_USERNAME`
+   - `DB_PASSWORD`
+
+3. Local prerequisites:
+   - `docker compose`
+   - `mkcert`
+   - `composer`
+   - `sudo`
+
+4. Runtime state:
+   - Docker daemon reachability
+   - `${APP_NAME}-api` container state
+   - `${APP_NAME}-mysql` container state
+
+---
+
+## Behavior
+
+- Report is printed with `ok`, `warning`, and `fail` statuses
+- Command exits with non-zero status when blocking failures are found
+- Warnings are shown for non-blocking but important setup gaps
+
+---
+
+## Files changed
+
+- `src/local/doctor.js` (new)
+- `bin/groups/local.js`
+- `README.md`
+
+---
+
+## Impact
+
+- Faster onboarding and troubleshooting for colleagues less familiar with the stack
+- Earlier detection of missing setup prerequisites
+- Fewer failed setup attempts caused by hidden local-state issues
+

package/docs/releases/release_2.2.1.md

@@ -0,0 +1,36 @@
+# Release 2.2.1 — Documentazione versioni precedenti
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+Release di manutenzione documentazione: aggiunge le release note e le voci
+di Changelog mancanti per le versioni `2.1.0` e `2.2.0`, garantendo
+traceabilità completa della storia del progetto.
+
+---
+
+## Changed
+
+- `docs/Changelog.md` aggiornato con le voci `2.1.0` e `2.2.0`
+- `docs/releases/release_2.1.0.md` aggiunto
+- `docs/releases/release_2.2.0.md` aggiunto
+- `README.md` aggiornato per allineamento con lo stato corrente
+
+---
+
+## Files changed
+
+- `README.md`
+- `docs/Changelog.md`
+- `docs/releases/release_2.1.0.md` (nuovo)
+- `docs/releases/release_2.2.0.md` (nuovo)
+
+---
+
+## Impact
+
+- Nessun impatto funzionale
+- Storia delle release ora completa e consultabile dal `docs/` del repository

package/docs/releases/release_2.2.2.md

@@ -0,0 +1,57 @@
+# Release 2.2.2 — Dynamic team lookup per operazioni DB
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+Migliora la selezione del nome utente nelle operazioni di database:
+invece di una lista hardcoded, il tool ora tenta di recuperare i membri
+del team tecnico via API JumpGroup, cadendo in fallback sulla lista locale
+solo se la chiamata non è disponibile.
+
+Aggiunge anche la domanda esplicita "vuoi attribuire il dump a un utente?"
+prima di mostrare la selezione, rendendo l'operazione opzionale.
+
+---
+
+## Added
+
+- `src/google/utilities.js` (nuovo):
+  - `getLocalKeys()` — legge `groupKey`/`groupSecret` da `.secret-fetcher`
+  - `getPeopleName()` — recupera i membri di `tech@jumpgroup.it` via API e
+    restituisce i firstname come `{ name, value }` per `@inquirer/select`
+
+- `src/google/groupMembers.js` (nuovo):
+  - `getMembersOfGroupEmail()` — chiama l'API Gmail Group Alias interna
+    per ottenere i membri di un gruppo
+
+---
+
+## Changed
+
+- `getUserName()` in `src/utilities/utilities.js`:
+  - Aggiunge conferma opzionale ("Do you want to add a User name to the DB?")
+    prima della selezione; se l'utente risponde no, restituisce `null`
+  - Tenta il recupero dinamico dei nomi dal team via `getPeopleName()`;
+    in caso di errore stampa un avviso e usa la lista locale come fallback
+  - Lista `TEAM_MEMBERS` aggiornata: aggiunti `anto` e `giulia`, rimosso `meg`
+
+---
+
+## Files changed
+
+- `src/google/groupMembers.js` (nuovo)
+- `src/google/utilities.js` (nuovo)
+- `src/utilities/utilities.js`
+
+---
+
+## Impact
+
+- La lista utenti nei dump DB è sempre aggiornata senza richiedere modifiche
+  al codice quando il team cambia
+- Il fallback locale garantisce che l'operazione funzioni anche senza
+  connettività all'API interna
+- L'attribuzione del nome è ora esplicitamente opzionale

package/docs/releases/release_2.2.3.md

@@ -0,0 +1,39 @@
+# Release 2.2.3 — Fix crash CloudFront su OAC duplicato
+
+**Date:** 2026-04-08
+
+---
+
+## Overview
+
+Corregge un crash in `getOriginAccessControlByName` causato da una
+discrepanza tra la struttura degli oggetti restituiti dall'API CloudFront
+durante il listing degli OAC e quella usata durante la creazione.
+
+---
+
+## Fixed
+
+- `getOriginAccessControlByName` in `src/aws/cloudfront.js`:
+  - L'accesso a `item.OriginAccessControl?.Name` falliva su oggetti restituiti
+    da `ListOriginAccessControls`, che espongono i campi direttamente
+    sull'elemento (es. `item.Name`) anziché annidati in `OriginAccessControl`
+  - Il risultato veniva ora normalizzato esplicitamente alla shape attesa dal
+    resto del codice (`Id`, `Name`, `Description`, `SigningProtocol`,
+    `SigningBehavior`, `OriginAccessControlOriginType`), eliminando accessi
+    a campi undefined e il conseguente crash
+
+---
+
+## Files changed
+
+- `src/aws/cloudfront.js`
+
+---
+
+## Impact
+
+- `media setup-general` e `media cloudfront setup` non crashano più
+  quando un OAC con lo stesso nome esiste già nell'account AWS
+- Il rilevamento dell'OAC esistente è ora affidabile per la logica
+  di idempotenza dei comandi media