@jumpgroup/laravel-tools 3.3.0

package/docs/releases/release_0.0.3.md

@@ -0,0 +1,58 @@
+# Release 0.0.3 — Cache command group
+
+**Date:** 2026-03-18
+
+---
+
+## Overview
+
+Implements the `cache` command group. Small and self-contained — no new design
+decisions required, fully reuses the utilities from 0.0.1.
+
+In trellis-tools, cache flushing meant clearing WordPress's object cache
+(Memcached/Redis via WP-CLI). For Laravel there is no single "object cache"
+command — instead, Laravel has four independent cache layers that each need to
+be cleared separately.
+
+---
+
+## Commands added
+
+| Command | What it does |
+|---------|-------------|
+| `cache flush-local` | Clears all Laravel caches in the local Docker app container |
+| `cache flush-remote` | Clears all Laravel caches on a remote server via SSH |
+| `cache flush-all` | Runs flush-local then flush-remote |
+
+---
+
+## Files added
+
+### `src/cache.js`
+Defines the four artisan commands to run on every flush:
+```
+php artisan cache:clear    — application cache (Redis / file)
+php artisan config:clear   — cached config files
+php artisan route:clear    — cached route list
+php artisan view:clear     — compiled Blade templates
+```
+
+- `flushLocal()` — iterates the four commands via `docker exec {APP_NAME}-app php artisan {cmd}`
+- `flushRemote(options)` — joins them with `&&` and runs them in a single SSH call
+- `flushAll(options)` — calls both in sequence
+
+### `bin/groups/cache.js`
+CLI layer only. Three Commander subcommands wired to `src/cache.js`.
+
+---
+
+## Design decisions
+
+- **Four commands instead of one** — unlike `wp cache flush`, there is no single
+  Laravel artisan command that clears everything. All four layers are always
+  cleared together to avoid partial state.
+- **Single SSH call for remote** — the four artisan commands are joined with `&&`
+  into one SSH invocation rather than four separate connections, for speed.
+- **No Q1 dependency** — local flush uses the already-decided container name
+  (`{APP_NAME}-app`); remote flush uses SSH via `laravel-tools.yml`, same as
+  the database commands. The deploy tool is not involved.

package/docs/releases/release_0.0.4.md

@@ -0,0 +1,128 @@
+# Release 0.0.4 — Local setup scripts + container name fixes
+
+**Date:** 2026-03-18
+
+---
+
+## Historical note
+
+This release note is kept for historical traceability only.
+
+It does **not** describe the current local workflow baseline anymore.
+The current source of truth is the `1.0.0` local workflow:
+
+1. `npx laravel-tools local setup-project`
+2. `yarn repo-setup`
+3. `yarn start`
+4. `yarn setup-laravel`
+
+Read the root `README.md` and `docs/Changelog.md` for the active workflow.
+
+## Overview
+
+Implements the `local` command group — the commands developers run to spin up a
+new Laravel project locally. Also fixes container naming across the codebase
+after analysing the real Laravel project structure.
+
+At the time of 0.0.4 the local workflow was:
+
+```
+1. laravel-tools local setup-project   (not built yet at the time)
+2. laravel-tools local setup-repo      ← built here
+   yarn repo-setup in boilerplate package.json calls this
+3. docker compose up -d
+   yarn start in boilerplate package.json calls this
+4. laravel-tools local setup-laravel   ← built here
+```
+
+---
+
+## Bug fixes
+
+### Wrong container names in `src/cache.js` and `src/database.js`
+The initial implementation assumed container names of `{APP_NAME}-app` and
+`{APP_NAME}-db`. After analysing the real Laravel project docker-compose.yml,
+the correct names are:
+
+| Wrong | Correct |
+|-------|---------|
+| `{APP_NAME}-app` | `{APP_NAME}-api` |
+| `{APP_NAME}-db` | `{APP_NAME}-mysql` |
+
+All references in `src/cache.js` and `src/database.js` updated.
+
+---
+
+## Stub files added (`src/stub/`)
+
+Template files that `setup-repo` copies into the project root, substituting
+`${VAR}` tokens with values from `.env`.
+
+### `src/stub/docker-compose.yml`
+Based on the real project docker-compose.yml, with:
+- Hardcoded names (`supporticket.test`) replaced with `${APP_NAME}.test`
+- Inconsistent volume mount path for mysql fixed (`./mysql/` → `./docker/mysql/`)
+- Services: `traefik`, `api` (`jumpgroupit/laravel-image:0.1.0`), `db` (MySQL 8.0)
+
+### `src/stub/docker/traefik/traefik.yml`
+Fixed leftover wrong network name: `ecommerce-network` → `api-network`.
+
+### `src/stub/docker/traefik/dynamic_conf.yml`
+Cert paths changed from hardcoded project-specific names to generic:
+- `site.test.pem` / `site.key`
+These are the names `setup-repo` renames the mkcert output to, so this file
+never needs to change between projects.
+
+### `src/stub/docker/php/local.ini`
+PHP configuration copied from the real project: upload limits, execution time,
+memory limit.
+
+### `src/stub/docker/mysql/my.cnf`
+Minimal MySQL config enabling the general query log.
+
+---
+
+## Commands added
+
+### `local setup-repo`
+Equivalent of trellis-tools `local setup-repo` (`setupLocal` in src/index.js).
+
+Flow:
+1. Assert `.env.example` and `.secret-fetcher` exist
+2. Inject secrets via `@jumpgroup/secret-fetcher::replaceSecrets()` → `.env`
+3. Copy all stub files to project root with variable substitution
+   (`@jumpgroup/secret-fetcher::replaceFiles()`)
+4. Create `docker/certs/` directory
+5. Run `mkcert {APP_NAME}.test` inside `docker/certs/`
+6. Rename certs to generic names (`site.test.pem`, `site.key`) so
+   `dynamic_conf.yml` works for any project without modification
+7. Add `{APP_NAME}.test` to `/etc/hosts` via `sudo hostile set`
+
+### `local setup-laravel`
+Equivalent of trellis-tools `local setup-wordpress` (`setupWordpress`).
+
+Flow:
+1. Assert `.env` exists (setup-repo must have run first)
+2. Check `{APP_NAME}-api` container is running
+3. If `APP_KEY` already present in `.env` (injected by secret-fetcher in
+   step 2), skip `key:generate` — avoids overwriting the vault key
+4. If `APP_KEY` missing, run `php artisan key:generate`
+5. Run `php artisan migrate`
+6. Optionally run `php artisan db:seed` (interactive confirm)
+
+---
+
+## Dependencies added to `package.json`
+
+| Package | Purpose |
+|---------|---------|
+| `@jumpgroup/secret-fetcher` | Secret injection and stub file deployment |
+| `glob` | File pattern matching (used by secret-fetcher stub copy) |
+| `hostile` | `/etc/hosts` editing via `sudo hostile set` |
+
+---
+
+## Other changes
+
+- `bin/tools.js`: registered `local` command group, removed unused `readFileSync`
+  import.

package/docs/releases/release_0.0.5.md

@@ -0,0 +1,77 @@
+# Release 0.0.5 — PHP version stubs + Docker image updates
+
+**Date:** 2026-03-20
+
+---
+
+## Overview
+
+Updates the Docker service versions in the stub to the latest stable versions
+compatible with macOS 15.2, and introduces PHP version variants for the
+docker-compose stub — mirroring the trellis-tools pattern. The `setup-repo`
+command now accepts a `--phpversion` flag to select which image to use.
+
+---
+
+## Docker image version updates (`src/stub/docker-compose.yml`)
+
+| Service | Before | After | Reason |
+|---------|--------|-------|--------|
+| `traefik` | `v2.4.7` | `v2.11` | Latest stable v2, macOS 15.2 compatible. Stayed on v2 (not v3) for consistency with existing projects |
+| `mysql` | `8.0` | `8.4` | Latest LTS release |
+| `jumpgroupit/laravel-image` | `0.1.0` | `0.2.5` | Latest release (PHP 8.4) |
+
+> Traefik v3 was evaluated and rejected — it has breaking config changes and
+> the team already runs v2.11 across all other projects.
+
+---
+
+## PHP version stub variants added
+
+New structure under `src/stub/docker-compose/`:
+
+```
+src/stub/
+  docker-compose.yml               ← default (PHP 8.4)
+  docker-compose/
+    php8.0/docker-compose.yml      ← jumpgroupit/laravel-image:0.2.2
+    php8.1/docker-compose.yml      ← jumpgroupit/laravel-image:0.2.3
+    php8.2/docker-compose.yml      ← jumpgroupit/laravel-image:0.1.0
+    php8.3/docker-compose.yml      ← jumpgroupit/laravel-image:0.2.4
+    php8.4/docker-compose.yml      ← jumpgroupit/laravel-image:0.2.5
+```
+
+PHP 8.0 and 8.1 are end-of-life but included for legacy project support.
+
+Image tag mapping (confirmed with team):
+
+| PHP version | Image tag |
+|-------------|-----------|
+| 8.0 | `jumpgroupit/laravel-image:0.2.2` |
+| 8.1 | `jumpgroupit/laravel-image:0.2.3` |
+| 8.2 | `jumpgroupit/laravel-image:0.1.0` |
+| 8.3 | `jumpgroupit/laravel-image:0.2.4` |
+| 8.4 | `jumpgroupit/laravel-image:0.2.5` |
+
+---
+
+## `--phpversion` flag added to `local setup-repo`
+
+```bash
+laravel-tools local setup-repo                      # default: php8.4
+laravel-tools local setup-repo --phpversion php8.2
+laravel-tools local setup-repo --phpversion php8.0
+```
+
+### How it works (`src/local/setup.js`)
+
+1. `replaceFiles` copies all stubs including the `docker-compose/` version subfolders
+2. If a non-default version is requested, `docker-compose.yml` is overwritten
+   with the version-specific file (with `${VAR}` tokens substituted from `.env`)
+3. The `docker-compose/` subfolder is removed from the project root — it is
+   internal to laravel-tools and not needed in the project
+
+### Files changed
+
+- `src/local/setup.js` — added `phpversion` option, version selection logic, cleanup
+- `bin/groups/local.js` — added `--phpversion` option with `.choices()` validation

package/docs/releases/release_0.0.6.md

@@ -0,0 +1,80 @@
+# Release 0.0.6 — Mailpit local mail service
+
+**Date:** 2026-03-20
+
+---
+
+## Overview
+
+Adds Mailpit as the local email testing service across all Docker Compose stubs.
+Mailpit replaces the originally requested Mailhog, which has not been maintained
+since 2021. Mailpit is a drop-in replacement with the same ports, actively
+maintained, and has a significantly better web UI.
+
+---
+
+## Why Mailpit over Mailhog
+
+| | Mailhog | Mailpit |
+|---|---|---|
+| Last release | 2021 | Active |
+| SMTP port | 1025 | 1025 |
+| Web UI port | 8025 | 8025 |
+| Web UI quality | Basic | Modern |
+| ARM64 support | Unofficial | Official |
+
+Both work identically from Laravel's perspective — only the image name changes.
+
+---
+
+## Changes to all Docker Compose stubs
+
+Files updated:
+- `src/stub/docker-compose.yml` (default, PHP 8.4)
+- `src/stub/docker-compose/php8.0/docker-compose.yml`
+- `src/stub/docker-compose/php8.1/docker-compose.yml`
+- `src/stub/docker-compose/php8.2/docker-compose.yml`
+- `src/stub/docker-compose/php8.3/docker-compose.yml`
+- `src/stub/docker-compose/php8.4/docker-compose.yml`
+
+### Service added: `mailpit`
+
+```yaml
+mailpit:
+  image: axllent/mailpit:latest
+  container_name: ${APP_NAME}-mailpit
+  restart: unless-stopped
+  ports:
+    - "1025:1025"   # SMTP — Laravel MAIL_HOST points here
+    - "8025:8025"   # Web UI — direct access
+  networks:
+    - api-network
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.mailpit.rule=Host(`mail.${APP_NAME}.test`)"
+    - "traefik.http.routers.mailpit.tls=true"
+    - "traefik.http.services.mailpit.loadbalancer.server.port=8025"
+```
+
+### `api` service: `depends_on` updated
+
+```yaml
+depends_on:
+  - db
+  - mailpit   ← added
+```
+
+---
+
+## Laravel `.env` configuration
+
+Any Laravel project using these stubs should have:
+
+```
+MAIL_MAILER=smtp
+MAIL_HOST=${APP_NAME}-mailpit
+MAIL_PORT=1025
+```
+
+The web UI is accessible at `https://mail.{APP_NAME}.test` after `setup-repo`
+adds the domain to `/etc/hosts` and Traefik routes it via the labels above.

package/docs/releases/release_1.0.0.md

@@ -0,0 +1,61 @@
+# Release 1.0.0 — Local workflow baseline
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+First baseline release where the Laravel local workflow is treated as the core product.
+This version establishes the 4-step setup model:
+
+```bash
+1. laravel-tools local setup-project
+2. yarn repo-setup
+3. yarn start
+4. yarn setup-laravel
+```
+
+The release also aligns the local setup model with the Trellis-style split between:
+- project identity definition
+- local repo preparation
+- runtime startup
+- application initialization
+
+## Added
+
+- New `local setup-project` command
+- Multi-repo workflow documentation for working across:
+  - `laravel-tools`
+  - Laravel boilerplate
+  - real Laravel reference project
+
+## Changed
+
+- `local setup-project` now prompts for the project name and updates:
+  - `APP_NAME`
+  - `APP_URL`
+  - `ASSETS_URL`
+  in `.env.example`
+- `local setup-repo` now focuses on local environment preparation only
+- Local setup now adds both:
+  - `${APP_NAME}.test`
+  - `mail.${APP_NAME}.test`
+  to `/etc/hosts`
+- Certificate generation now supports both local hosts
+- Docker stub templating now prefers `DB_DATABASE` while preserving `DB_NAME` compatibility
+- Database import cleanup now clears all four Laravel cache layers
+- Local Traefik/MySQL defaults were updated to the current baseline:
+  - Traefik `v3.6.11`
+  - MySQL `max_allowed_packet = 256M`
+  - query log disabled by default
+
+## Fixed
+
+- Missing `.secret-fetcher` during `local setup-project` now fails with the standard team-specific message:
+  `Secret fetcher non è inizializzato, contattare Giada o Andrea`
+
+## Notes
+
+- This is the first version intended as a serious baseline for testing the Laravel local workflow end-to-end.
+- Earlier `0.x` releases remain the pre-baseline build-up history.

package/docs/releases/release_1.0.1.md

@@ -0,0 +1,18 @@
+# Release 1.0.1 — Stub copy target fix
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Hotfix for a critical `local setup-repo` issue discovered during real project testing.
+
+## Fixed
+
+- Corrected the destination passed to `replaceFiles(...)` so the project root is treated as a directory, not as a file path
+- Prevented `EISDIR: illegal operation on a directory` failures while copying generated Docker/Traefik stubs into the target repo
+
+## Impact
+
+- `local setup-repo` can now complete the stub copy phase on real Laravel projects

package/docs/releases/release_1.0.2.md

@@ -0,0 +1,18 @@
+# Release 1.0.2 — Session migration bootstrap
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Fixes local Laravel initialization for projects that rely on a sessions table but do not already ship the migration.
+
+## Fixed
+
+- `local setup-laravel` now attempts to generate the session-table migration before running migrations
+- Reduced first-run failures caused by missing `create_sessions_table` migrations
+
+## Impact
+
+- More reliable bootstrap on fresh Laravel projects during step 4 of the local workflow

package/docs/releases/release_1.0.3.md

@@ -0,0 +1,19 @@
+# Release 1.0.3 — Target `.gitignore` safety
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Improves generated-project hygiene during local repo preparation.
+
+## Added
+
+- `local setup-repo` now appends missing local-only entries to the target project's `.gitignore`:
+  - `mysql/`
+  - `docker/certs/`
+
+## Impact
+
+- Generated local artifacts are less likely to show up as noisy untracked files in consumer projects

package/docs/releases/release_1.1.0.md

@@ -0,0 +1,18 @@
+# Release 1.1.0 — Optional Filament install
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Extends Laravel bootstrap with an optional Filament installation flow.
+
+## Added
+
+- `local setup-laravel` now asks whether Filament should be installed during setup
+- If confirmed, the setup flow starts the Composer require + Filament installation sequence inside the running app container
+
+## Impact
+
+- New Laravel projects can bootstrap Filament directly from the standard local setup flow

package/docs/releases/release_1.1.1.md

@@ -0,0 +1,17 @@
+# Release 1.1.1 — Composer constraint fix for Filament
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Quick fix for the initial Filament installation command added in `1.1.0`.
+
+## Fixed
+
+- Corrected the `composer require` syntax used for `filament/filament:^3.2`
+
+## Impact
+
+- Filament installation no longer fails because of an invalid Composer package constraint

package/docs/releases/release_1.1.2.md

@@ -0,0 +1,18 @@
+# Release 1.1.2 — Filament user command
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Adds a dedicated helper command for creating a Filament user in the local environment.
+
+## Added
+
+- New `local user add` command
+- The command runs `php artisan make:filament-user` inside the running `${APP_NAME}-api` container
+
+## Impact
+
+- Filament-enabled projects can create admin users without leaving the tool flow

package/docs/releases/release_1.1.3.md

@@ -0,0 +1,21 @@
+# Release 1.1.3 — Composer/install output cleanup
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Improves the visibility and ordering of setup output while hardening session migration handling.
+
+## Added
+
+- `local setup-repo` now runs `composer install` explicitly as part of the repo preparation phase
+
+## Changed
+
+- Composer installation output now appears in the expected place during setup instead of surfacing later from asynchronous container startup
+
+## Fixed
+
+- Session migration checks were tightened before running Laravel migrations

package/docs/releases/release_1.1.4.md

@@ -0,0 +1,18 @@
+# Release 1.1.4 — Session migration detection via `readdirSync`
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Refines the session-table detection introduced in the previous releases.
+
+## Fixed
+
+- Replaced `glob`-based session migration detection with `readdirSync` on `database/migrations`
+- Reduced false negatives / false positives when checking whether `create_sessions_table` already exists
+
+## Impact
+
+- `local setup-laravel` is more deterministic when deciding whether to generate the session migration

package/docs/releases/release_1.1.5.md

@@ -0,0 +1,18 @@
+# Release 1.1.5 — Non-interactive Filament install
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Removes interactive noise from the Filament setup phase.
+
+## Fixed
+
+- `php artisan filament:install` now runs with `--no-interaction`
+- Removed self-spam / TTY-related friction during automated local setup
+
+## Impact
+
+- Filament installation is smoother and better behaved inside scripted setup flows

package/docs/releases/release_1.1.6.md

@@ -0,0 +1,21 @@
+# Release 1.1.6 — Graceful migrations
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Stabilizes the final migration phase of local Laravel initialization.
+
+## Changed
+
+- `local setup-laravel` now runs `php artisan migrate --graceful`
+
+## Fixed
+
+- Session-table detection naming/flow was cleaned up before the final migration step
+
+## Impact
+
+- Migration execution is more tolerant during repeated setup runs

package/docs/releases/release_1.1.7.md

@@ -0,0 +1,17 @@
+# Release 1.1.7 — Filament assets in setup flow
+
+**Date:** 2026-04-02
+
+---
+
+## Overview
+
+Completes the Filament bootstrap sequence by publishing its assets during setup.
+
+## Added
+
+- `local setup-laravel` now runs `php artisan filament:assets` after Filament installation
+
+## Impact
+
+- Filament panels are more likely to be usable immediately after the setup flow completes