@jumpgroup/laravel-tools 3.3.0

package/docs/Changelog.md

@@ -0,0 +1,267 @@
+# Changelog
+
+All releases are documented in detail in `docs/releases/`.
+
+---
+
+## [3.3.0] — 2026-04-24
+### Added
+- Nuovo comando `forge server delete`: seleziona un server Forge e lo elimina con prompt distruttivo (default N)
+### Changed
+- Convenzione domini aggiornata al prefisso `api.` in tutti gli ambienti:
+  - Locale: `api.{appName}.test` (era `{appName}.test`) — certificati SSL, `/etc/hosts`, `APP_URL`, `ASSETS_URL`
+  - `forge site create`: dominio pre-compilato con `api.{appName}.sitointest.it` (staging) o `api.{appName}.it` (production), modificabile dall'utente
+### Fixed
+- Import mancante di `select` in `bin/groups/forge.js` causava crash in `forge site create` al passo selezione provider Git
+
+## [3.2.1] — 2026-04-24
+### Changed
+- `forge site create` aggiunge automaticamente `php artisan migrate --force` al deploy script quando il server è di tipo staging (nome contiene "staging")
+- Le migrazioni su production restano manuali via UI Forge
+
+## [3.2.0] — 2026-04-24
+### Added
+- Nuovo comando `forge site create`: crea un sito Laravel su un server Forge esistente e installa il repository Git
+- Selezione provider Git (GitHub/GitLab/Bitbucket), repository (`org/repo`) e branch
+- Nome database suggerito da `APP_NAME`, PHP version da `composer.json`
+- Polling fino a `status=installed` (ogni 5s, timeout 5 min) poi install repo + composer automatico
+- Output riepilogo con hint passi successivi (`forge env set` → `forge deploy`)
+- `createSite`, `pollSiteInstalled`, `installGitRepo` in `src/forge/sites.js`
+
+## [3.1.0] — 2026-04-24
+### Added
+- Nuovo comando `forge server create`: provisioning server AWS Lightsail tramite Forge API
+- Auto-incremento nome server per pattern blue/green (`myapp-staging` → `myapp-staging-2` → ...) con conferma prima di procedere
+- Lettura versione PHP da `composer.json` per allineamento automatico locale/remoto
+- Selezione regione (eu-central-1 / us-west-2), piano Lightsail e Redis opzionale
+- Polling provisioning con progress dots (ogni 20s, timeout 25 min)
+- `src/forge/provisioning.js`: `getAwsCredential`, `getSizesForRegion`, `readPhpVersionFromComposer`, `resolveServerName`, `createServer`, `pollServerReady`
+
+## [3.0.1] — 2026-04-23
+### Fixed
+- `getServerPath` legge ora il campo `path` da `laravel-tools.yml` invece di derivarlo dall'`APP_NAME` con il path Deployer errato (`/var/www/{app}/current`)
+- Errore esplicito se `path` manca dalla configurazione dell'ambiente
+- `cache flush-remote` passava `appName` invece di `env` a `getServerPath`
+### Changed
+- `getServerPath` spostato da `pathUtils.js` a `command.js` (stessa fonte: `laravel-tools.yml`)
+
+## [3.0.0] — 2026-04-23
+### Added
+- Nuovo gruppo comandi `forge`: integrazione con Laravel Forge API (nuova `/api`, non legacy `/api/v1`)
+- `forge token set` — salva il token in `~/.laravel-tools`
+- `forge servers` — elenca i server dell'account
+- `forge deploy` — seleziona server/sito e avvia deploy
+- `forge env get` / `forge env set` — legge/sovrascrive il `.env` remoto (set con prompt distruttivo in rosso)
+- `forge logs` — stampa il log dell'ultimo deploy
+- `src/forge/` — client HTTP nativo (`fetch`), config globale, server e site helpers
+
+## [2.2.5] — 2026-04-23
+
+### Added
+- `executeCommandWithOutput` utility in `command.js`: cattura stdout/stderr e li include nel messaggio di errore in caso di exit code non-zero
+- Health check Laravel post-setup via `php artisan about` alla fine di `local setup-laravel`
+- Recovery automatico senza Filament: `composer install`, `package:discover`, `storage:link`, `optimize:clear` + secondo tentativo di health check
+- Log di conferma `✅ Bootstrap Laravel verificato.` al termine del health check riuscito
+### Changed
+- `runLaravelHealthCheck` usa `executeCommandWithOutput`: l'output artisan è ora visibile negli errori
+- `runNoFilamentRecovery` include ora anche `storage:link` nel flusso di recovery
+- Errori post-health check ora in italiano con output artisan allegato (sia per Filament che per recovery fallito)
+
+## [2.2.4] — 2026-04-08
+### Added
+- `getBucketOriginDomainCandidates()` e `getDistributionForProjectStrict()` in `cloudfront.js`: lookup deterministico vincolato a origin S3 + tag/comment con gestione esplicita dei duplicati
+- Campo `originDomainNames` nei row CloudFront per supportare il match sull'origin
+### Fixed
+- `resolveOrCreateDistributionForProject` usa ora `getDistributionForProjectStrict` invece di `getDistributionByProjectTagStrict`, eliminando il rischio di creare distribuzioni duplicate
+- `getDistributionsByProjectTag` aggiunge fallback su `comment` quando il tag lookup AWS è temporaneamente non disponibile; lancia errore esplicito se il lookup fallisce completamente
+- `PutObjectCommand` in `bucket.js`: `Body` ora è `Buffer.alloc(0)` invece di stringa vuota per compatibilità aws-sdk
+
+## [2.2.3] — 2026-04-08
+### Fixed
+- `getOriginAccessControlByName` in `cloudfront.js`: corretto crash causato da discrepanza tra la shape degli oggetti OAC nel listing AWS e quella restituita dalla creazione; i campi sono ora normalizzati esplicitamente
+
+## [2.2.2] — 2026-04-08
+### Added
+- `src/google/groupMembers.js`: `getMembersOfGroupEmail()` per recupero membri da API Gmail Group Alias interna
+- `src/google/utilities.js`: `getLocalKeys()` e `getPeopleName()` per lettura credenziali `.secret-fetcher` e lookup dinamico nomi team
+### Changed
+- `getUserName()` in `utilities.js`: aggiunta conferma opzionale prima della selezione, recupero dinamico dei nomi team via API con fallback sulla lista locale
+- Lista `TEAM_MEMBERS` aggiornata: aggiunti `anto` e `giulia`
+
+## [2.2.1] — 2026-04-08
+### Changed
+- Aggiunta documentazione mancante per versioni `2.1.0` e `2.2.0`: release note e voci Changelog
+
+## [2.2.0] — 2026-04-08
+### Added
+- New `local doctor` command to run a fast diagnostic of the local Laravel project state
+### Checks
+- Presence/availability checks for key files: `.env.example`, `.secret-fetcher`, `.env`, `docker-compose.yml`, local cert files, `laravel-tools.yml`
+- Minimal `.env.example` key validation (`APP_NAME`, `APP_URL`, `ASSETS_URL`, DB credentials)
+- Local dependency checks (`docker compose`, `mkcert`, `composer`, `sudo`)
+- Docker daemon reachability and `${APP_NAME}-api` / `${APP_NAME}-mysql` container status
+### Behavior
+- Doctor output is grouped as `ok`, `warning`, `fail`
+- Command exits with non-zero status when blocking failures are detected
+
+## [2.1.0] — 2026-04-08
+### Changed
+- Database command group hardened for safer operational usage on local and remote flows
+### Added
+- `--dry-run` support on:
+  `database remote-export`, `database local-import`, `database local-export`, `database remote-import`
+### Fixed
+- `database remote-import` now asks explicit confirmation before import
+- `database remote-import` now asks whether to create a pre-import remote backup
+- On remote import failure, rollback guidance is printed when backup was created
+- Post-import remote DB health check (`SELECT 1`) added before final success
+- Remote temporary dump cleanup now depends on successful import completion
+
+## [2.0.3] — 2026-04-07
+### Changed
+- Reduced unnecessary AWS API usage during media dry-runs
+### Fixed
+- Dry-run distribution setup now skips strict CloudFront lookup and goes straight through the simulated creation path
+- Dry-run IAM setup no longer resolves the real CloudFront distribution when no ID was provided
+- Media dry-runs now use a deterministic simulated CloudFront ID when needed, avoiding avoidable read calls during preview-only execution
+
+## [2.0.2] — 2026-04-07
+### Fixed
+- Corrected another dry-run edge case in media IAM setup
+- Dry-run access key generation now behaves coherently when the target IAM user does not exist yet, avoiding an unnecessary `ListAccessKeys` call path
+- `media setup-iam` / full media setup dry-runs now return deterministic placeholder credentials for brand-new users instead of tripping over real IAM key listing logic
+
+## [2.0.1] — 2026-04-07
+### Fixed
+- Corrected a dry-run glitch in CloudFront bucket policy setup
+- `applyCloudFrontReadPolicy(...)` now exits before performing AWS reads/writes when `dryRun` is enabled
+- Media dry-runs no longer attempt to fetch or mutate the current S3 bucket policy before the dry-run short-circuit
+
+## [2.0.0] — 2026-04-07
+### Added
+- New `media` command group for AWS media infrastructure management
+- `media setup-general` to provision or reconcile the full media stack for a project:
+  S3 bucket, CloudFront distribution, bucket read policy and IAM user credentials
+- `media setup-iam` to create or rotate the dedicated media IAM user credentials
+- S3 inspection helpers:
+  `media s3 list`, `media s3 get`
+- CloudFront inspection/setup helpers:
+  `media cloudfront list`, `media cloudfront get`, `media cloudfront setup`
+- AWS account resolution via STS to build CloudFront-scoped S3 bucket policies
+### Changed
+- `local setup-project` now optionally offers AWS media stack setup after updating project identity
+- `.env.example` can now be enriched with media-related values during setup:
+  `AWS_DEFAULT_REGION`, `AWS_BUCKET`, `AWS_URL`, `CLOUDFRONT_DISTRIBUTION_ID`, `CLOUDFRONT_DOMAIN`, `S3_SITE_BUCKET`, `S3_UPLOADS_BUCKET_URL`
+### Security
+- Media storage is configured as a private S3 bucket behind CloudFront Origin Access Control (OAC)
+- Bucket policies are now merged/idempotent so reruns preserve unrelated statements while ensuring CloudFront read access
+- IAM access key rotation for the media user is now safe: new key first, old key removed only after successful creation
+
+## [1.1.7] — 2026-04-02
+### Added
+- `local setup-laravel` now runs `php artisan filament:assets` after Filament installation, so generated panels have their assets published immediately
+
+## [1.1.6] — 2026-04-02
+### Changed
+- `local setup-laravel` now runs Laravel migrations with `php artisan migrate --graceful`
+### Fixed
+- Session-table migration detection was stabilized before running migrations, reducing false positives around `create_sessions_table`
+
+## [1.1.5] — 2026-04-02
+### Fixed
+- Filament installation during `local setup-laravel` now uses `--no-interaction`, removing self-spam / interactive noise during setup
+
+## [1.1.4] — 2026-04-02
+### Fixed
+- Session migration detection now uses `readdirSync` on `database/migrations` instead of `glob`, making the check more reliable in local setup
+
+## [1.1.3] — 2026-04-02
+### Added
+- `local setup-repo` now ensures `mysql/` and `docker/certs/` are added to the target project's `.gitignore` when missing
+### Changed
+- Composer dependency installation is now executed explicitly during `local setup-repo`, keeping output ordered and visible in the setup flow
+### Fixed
+- Session-table generation logic was hardened before running migrations
+
+## [1.1.2] — 2026-04-02
+### Added
+- New `local user add` command to create a Filament user in the running `${APP_NAME}-api` container
+
+## [1.1.1] — 2026-04-02
+### Fixed
+- Corrected the Composer package constraint used when requiring `filament/filament` during setup
+
+## [1.1.0] — 2026-04-02
+### Added
+- `local setup-laravel` now optionally offers Filament installation during Laravel bootstrap
+
+## [1.0.3] — 2026-04-02
+### Added
+- `local setup-repo` can now append missing local artifact folders to the target project's `.gitignore`
+
+## [1.0.2] — 2026-04-02
+### Fixed
+- `local setup-laravel` now generates the session migration when needed before running Laravel migrations
+
+## [1.0.1] — 2026-04-02
+### Fixed
+- Corrected stub-copy target handling in `local setup-repo`, preventing the repo root from being treated as a file during `replaceFiles`
+
+## [1.0.0] — 2026-04-02
+### Added
+- Documented the recommended multi-repo Codex workflow for working across `laravel-tools`, a Laravel boilerplate repo, and a real Laravel reference project
+- Added `local setup-project` to define the local project identity before preparing the repo
+### Changed
+- Local Laravel workflow now documented as 4 explicit steps:
+  `npx laravel-tools local setup-project` -> `yarn repo-setup` -> `yarn start` -> `yarn setup-laravel`
+- `local setup-project` now prompts for the project name, normalizes it, and updates `APP_NAME`, `APP_URL` and `ASSETS_URL` in `.env.example`
+- `local setup-repo` now focuses on local environment preparation and adds both `${APP_NAME}.test` and `mail.${APP_NAME}.test` to `/etc/hosts`
+- Traefik Docker stubs updated from `v2.11` to `v3.6.11` now that the previously known macOS compatibility issue is resolved
+- Traefik static config updated alongside the v3 move so generated local environments use the validated v3 baseline
+- MySQL local stub now sets `max_allowed_packet = 256M` and leaves `general_log` disabled by default
+- Docker Compose stubs now prefer Laravel-native `DB_DATABASE`, while CLI database operations remain compatible with legacy `DB_NAME`
+- Database import flow now clears all four Laravel caches (`cache`, `config`, `route`, `view`) for consistency with the `cache` command group
+### Fixed
+- Missing `.secret-fetcher` during `local setup-project` now fails immediately with the standardized message:
+  `Secret fetcher non è inizializzato, contattare Giada o Andrea`
+
+## [0.0.6] — 2026-03-20
+### Added
+- Mailpit (`axllent/mailpit:latest`) added to all Docker Compose stubs as local mail service
+- Mailpit accessible via SMTP on port `1025` and web UI on `mail.{APP_NAME}.test` via Traefik
+### Replaced
+- Mailhog (unmaintained since 2021) not added — went straight to Mailpit as the maintained alternative
+
+## [0.0.5] — 2026-03-20
+### Added
+- PHP version stub variants: `docker-compose/php8.0` through `php8.4`
+- `--phpversion` flag on `local setup-repo` to select the Docker image
+### Changed
+- `traefik` updated `v2.4.7` → `v2.11` (stayed on v2 for consistency with existing projects)
+- `mysql` updated `8.0` → `8.4`
+- `jumpgroupit/laravel-image` updated `0.1.0` → `0.2.5` (PHP 8.4, latest)
+
+## [0.0.4] — 2026-03-18
+### Added
+- `local` command group: `setup-repo`, `setup-laravel`
+- Docker stub files for Laravel (`docker-compose.yml`, traefik, php.ini, my.cnf)
+- Dependencies: `@jumpgroup/secret-fetcher`, `glob`, `hostile`
+### Fixed
+- Container names corrected across `cache` and `database` modules:
+  `{APP_NAME}-app` → `{APP_NAME}-api`, `{APP_NAME}-db` → `{APP_NAME}-mysql`
+
+## [0.0.3] — 2026-03-18
+### Added
+- `cache` command group: `flush-local`, `flush-remote`, `flush-all`
+- Clears Laravel caches (`cache:clear`, `config:clear`, `route:clear`, `view:clear`) locally via Docker and remotely via SSH
+
+## [0.0.2] — 2026-03-18
+### Added
+- `database` command group: `remote-export`, `local-import`, `local-export`, `remote-import`, `list`
+- Google Drive integration for dump storage (via OS keyring)
+
+## [0.0.1] — 2026-03-18
+### Added
+- Project scaffolding: `package.json`, `.gitignore`, `bin/tools.js` entry point
+- All shared utilities: `command`, `dateUtils`, `fileUtils`, `google-drive`, `pathUtils`, `userInput`, `utilities`
+- Server connection config via `laravel-tools.yml` (host + SSH user per environment)

package/docs/TODO.md

@@ -0,0 +1,167 @@
+# TODO
+
+This file tracks implementation work that is still pending in `laravel-tools`.
+
+---
+
+## Remote Environments (Staging/Production)
+
+### Why this is needed
+
+`database remote-export` and `database remote-import` already exist, but they rely on
+remote connection metadata (`host`, `user`) that is not generated by any server setup
+flow in `laravel-tools`.
+
+In `trellis-tools`, this gap is solved by `server setup`, which creates/reuses servers
+and updates local config files used by remote commands.
+
+Current `laravel-tools` state:
+- remote DB scripts are present
+- remote server creation lifecycle is missing
+- companion file updates are missing
+
+---
+
+## What is already done
+
+- `database remote-export` implemented
+- `database remote-import` implemented
+- `database local-export` implemented
+- `database local-import` implemented
+- remote import hardening added:
+  - confirm prompt before import
+  - optional pre-import backup prompt
+  - rollback command shown on failure
+  - post-import DB health check (`SELECT 1`)
+  - cache clear after import
+  - dry-run support
+
+---
+
+## Missing elements for full remote lifecycle
+
+### 1) Server setup command group (new)
+
+- Add a `server` command group in `laravel-tools`
+- Add `server setup` command for company flow (`staging`, `production`)
+- Scope first implementation to Lightsail only
+- Region support aligned with team usage (`eu-central-1`, `eu-west-1`)
+
+Acceptance criteria:
+- command can create or reuse a server for selected env
+- command returns public IP and instance metadata
+- command is safe on reruns
+
+### 2) Remote metadata persistence (required by DB/cache scripts)
+
+- Establish one canonical project file for remote metadata:
+  - `laravel-tools.yml`
+- Ensure it contains:
+  - `staging.host`
+  - `staging.user`
+  - `production.host`
+  - `production.user`
+- `server setup` must update this file automatically after provisioning or IP change
+
+Acceptance criteria:
+- no manual IP copy needed after server setup
+- remote DB/cache commands work immediately after setup
+
+### 3) Server companion actions (minimal parity with trellis workflow)
+
+- SSH readiness check after creation
+- Optional static IP association flow
+- Minimal firewall baseline (SSH + HTTPS; optional team ports)
+- Optional DNS/SMTP hooks should be deferred to a later phase unless explicitly requested
+
+Acceptance criteria:
+- server can be reached via SSH with configured user
+- rerun does not duplicate or corrupt existing infra state
+
+### 4) Runtime validations in remote commands
+
+- Keep strict env handling (`staging`, `production`)
+- Improve error quality when `laravel-tools.yml` is missing/incomplete
+- Add explicit preflight in remote database/cache commands:
+  - verify `host` and `user` for selected env
+  - fail with actionable message
+
+Acceptance criteria:
+- failure messages tell exactly what key is missing and where
+
+### 5) Documentation and release notes
+
+- Add `Server` command documentation in `docs/commands` equivalent structure used by repo
+- Update README with remote environment lifecycle:
+  - create server
+  - auto-write `laravel-tools.yml`
+  - run remote DB/cache commands
+- Add release notes for the new server lifecycle feature
+
+Acceptance criteria:
+- a new dev can setup remote env without tribal knowledge
+
+---
+
+## Suggested implementation order
+
+1. Add `server setup` skeleton + CLI wiring
+2. Implement Lightsail create/reuse flow
+3. Implement `laravel-tools.yml` upsert writer
+4. Add preflight checks in remote database/cache flows
+5. Add static IP/firewall baseline
+6. Write docs and release notes
+
+---
+
+## Explicitly out of scope for this phase
+
+- Compressed DB dumps (`.sql.gz`)
+- Dynamic arbitrary environments beyond company-standard `staging` and `production`
+- Full Trellis-level DNS/SES automation in first pass
+- EC2 parity before Lightsail flow is stable
+
+---
+
+## Backlog (low priority)
+
+- `media setup-alias-cloudfront`
+  - Purpose: attach `media.<domain>` alias + ACM cert + DNS record to an existing CloudFront distribution
+  - Status: deferred (currently considered low value compared to server lifecycle and remote workflow foundations)
+
+- `certificate` command group (ACM)
+  - Purpose: request/get/delete ACM certificates and automate DNS validation records when needed
+  - Typical use: prerequisite for CloudFront aliases/custom domains
+  - Status: deferred
+
+- `smtp setup` command group (SES/SNS)
+  - Purpose: automate transactional email setup for project environments
+  - Expected scope:
+    - create/verify SES identity for project domain/subdomain
+    - generate SMTP credentials (IAM-backed)
+    - optionally wire SNS notifications for bounce/complaint visibility
+    - push resulting config/secrets into project env + `.secret-fetcher`
+  - Impact:
+    - removes repetitive manual AWS Console setup
+    - reduces go-live risk from missing DNS/auth configuration
+    - standardizes mail setup across `staging` and `production`
+  - Status: deferred
+
+- `budget` command group (AWS Budgets)
+  - Purpose: project-level cost governance from CLI
+  - Expected scope:
+    - list/get/create/update/delete budgets
+    - optional bulk cleanup by project tag/pattern
+    - email alert thresholds for monthly spend
+  - Impact:
+    - adds spending visibility and alerts per project
+    - reduces manual AWS console operations for budget management
+  - Status: deferred
+
+---
+
+## Open decisions (to confirm before coding server setup)
+
+- Default SSH user to write in `laravel-tools.yml` (`deployer` vs other)
+- Whether static IP should be mandatory or optional by default
+- Whether server setup should always be interactive or support a fully scripted mode

package/docs/releases/release_0.0.1.md

@@ -0,0 +1,116 @@
+# Release 0.0.1 — Project scaffolding & utilities
+
+**Date:** 2026-03-18
+
+---
+
+## Overview
+
+First commit. Establishes the project structure and all shared utility modules
+that every future command group will depend on. No commands are usable yet —
+this is the foundation layer.
+
+The architecture mirrors `@jumpgroup/trellis-tools` exactly: a `bin/` layer for
+CLI definitions only (Commander.js), and a `src/` layer for all business logic.
+
+---
+
+## Files added
+
+### `package.json`
+Defines the package as `@jumpgroup/laravel-tools`. Entry point is `bin/tools.js`,
+exposed as the `laravel-tools` binary. Only the dependencies needed so far are
+included — more will be added as command groups are built.
+
+### `.gitignore`
+Mirrors trellis-tools. Excludes: `node_modules/`, `.env`, `docker/`,
+`docker-compose.yml`, `.secret-fetcher`, `.laravel-tools`, `laravel-tools.yml`.
+
+### `bin/tools.js`
+Entry point. Imports all command group modules, registers them with Commander.js,
+calls `program.parse()`. Currently only wires up the `database` group
+(added in 0.0.2).
+
+### `src/utilities/command.js`
+Core execution and config-reading utilities:
+- `executeCommand(command, args, options)` — runs shell commands, streams
+  stdout/stderr to the terminal, returns a Promise.
+- `getIp(environment)` — reads server IP from `laravel-tools.yml::{env}.host`.
+  In trellis-tools this read from `trellis/hosts/{env}.yml`. Replaced with a
+  project-level YAML file that developers fill in manually until `server setup`
+  can write it automatically (pending Q1).
+- `getSshUser(environment)` — reads SSH user from `laravel-tools.yml::{env}.user`.
+  In trellis-tools this was hardcoded to `web` (a Trellis-provisioned user).
+  For Laravel the user depends on how the server is provisioned, so it is
+  configurable per environment.
+- `getAppName()` — reads `APP_NAME` from `.env.example`. In trellis-tools this
+  also fell back to `wordpress_sites.yml` — not needed for Laravel.
+
+**`laravel-tools.yml` format expected by this module:**
+```yaml
+staging:
+  host: 1.2.3.4
+  user: deployer
+
+production:
+  host: 5.6.7.8
+  user: deployer
+```
+
+### `src/utilities/dateUtils.js`
+- `getCurrentDateString()` → `YYYYMMDD` string. Used in database dump filenames.
+
+### `src/utilities/fileUtils.js`
+- `find10LatestFiles(directory, envFilter, usernameFilter)` — lists up to 10
+  most recent `.sql` files in a directory, sorted newest-first, with size and
+  date metadata. Used by the database command group for dump selection.
+- `filterDatabaseFiles(files, env, username)` — filters a file list by
+  environment and optional username token.
+
+### `src/utilities/google-drive.js`
+- `getGoogleDriveDirectory()` — returns the path to the Google Drive shared
+  drives folder. Checks the OS keyring first (keytar), then tries to locate the
+  folder automatically (Google Drive for Desktop on macOS mounts under
+  `~/Library/CloudStorage/GoogleDrive-{email}/`), then prompts the user if not
+  found. Saves the result to the keyring so subsequent calls are instant.
+  Service name changed from `trellis-tools` to `laravel-tools`.
+
+### `src/utilities/pathUtils.js`
+- `getServerPath(appname)` → `/var/www/{appname}/current`. This is the
+  Deployer/Capistrano-style deploy path assumed for Laravel servers. In
+  trellis-tools this was `/srv/www/{appname}/current` (set by Trellis).
+  **Will be confirmed once Q1 is answered.**
+- `ensureDirectoryExists(path)` — creates a directory recursively if it
+  doesn't exist.
+- `resolveDatabasePath(appname, customPath)` — returns
+  `{GoogleDriveDirectory}/Tech/DumpsDB/{appname}`. Mirrors trellis-tools exactly.
+
+### `src/utilities/userInput.js`
+- `askYesNo(message)` — confirm prompt via `@inquirer/prompts`.
+- `generateDatabaseFilename(appname, env, date, customName, amsMode, username)`
+  — generates the standard dump filename. Mirrors trellis-tools conventions:
+  - AMS mode: `{app}_ams{YEAR}_{env}.sql`
+  - Standard: `{app}_{env}_{YYYYMMDD}[_{username}].sql`
+  - Custom: `{customName}.sql`
+
+### `src/utilities/utilities.js`
+- `checkIfEnvFilesExist()` — asserts `.env.example` is present. Throws with
+  the standard Italian error message if not.
+- `getEnvironment()` — interactive `staging` / `production` selector.
+- `getUserName()` — interactive selector for the team member list (used to
+  attribute dump filenames). List is hardcoded: `giada`, `andre`, `meg`,
+  `betta`, `erica`, `chris`, `simo`, `pier`. Includes a "Nessuno" option to
+  skip attribution.
+- `generateRandomPassword(length)` — alphanumeric random password generator.
+
+---
+
+## Design decisions
+
+- **`laravel-tools.yml` for server config** — replaces the Trellis Ansible
+  inventory files. Developers fill it in manually for now. Once Q1 is answered,
+  `server setup` will write it automatically.
+- **Laravel env var naming** — uses `DB_USERNAME` and `DB_DATABASE` (Laravel
+  defaults) instead of trellis-tools' `DB_USER` and `DB_NAME`.
+- **ES modules throughout** — `"type": "module"` in `package.json`, matching
+  trellis-tools.

package/docs/releases/release_0.0.2.md

@@ -0,0 +1,88 @@
+# Release 0.0.2 — Database command group
+
+**Date:** 2026-03-18
+
+---
+
+## Overview
+
+Implements the full `database` command group — the first fully usable feature
+of laravel-tools. Covers the complete lifecycle of database dumps: export from
+remote, download locally, import locally, export locally, upload and import to
+remote, and list available dumps.
+
+Mirrors trellis-tools `database` commands 1:1 in structure and flow, with two
+key adaptations:
+- `wp db export` / `wp db import` (WP-CLI) → `mysqldump` / `mysql` (direct)
+- `wp cache flush` → `php artisan cache:clear` + `config:clear`
+
+---
+
+## Commands added
+
+| Command | What it does |
+|---------|-------------|
+| `database remote-export` | SSH to server, mysqldump, scp to local Google Drive, delete remote copy |
+| `database local-import` | Pick a dump from Google Drive, pipe into local Docker MySQL, clear caches |
+| `database local-export` | mysqldump from local Docker MySQL, save to Google Drive |
+| `database remote-import` | Pick a dump, scp to server, mysql import, clear remote caches, delete remote copy |
+| `database list` | List the 10 most recent dumps in Google Drive for this project |
+
+All commands support `-e / --environment` (staging/production) and `--ams` flag.
+`remote-export` and `local-export` also support `-n / --name` for a custom filename.
+
+---
+
+## Files added
+
+### `src/database.js`
+Five exported async functions, one per command. Key implementation details:
+
+**`remoteDownload` (remote-export)**
+Connects via SSH, runs `source .env && mysqldump` on the server so that DB
+credentials are read from the server's own `.env` — no credentials need to be
+passed from the developer's machine. Downloads via `scp`, then removes the
+remote copy.
+
+**`dbLocalImport` (local-import)**
+Reads DB credentials from the local `.env`. Pipes the selected dump file into
+`docker exec -i {APP_NAME}-db mysql` using a shell redirect (`sh -c "... < file"`).
+After import, runs `cache:clear` and `config:clear` via `docker exec {APP_NAME}-app`.
+
+**`dbLocalExport` (local-export)**
+Runs `docker exec {APP_NAME}-db mysqldump` via a shell redirect to write the
+output to a file in Google Drive.
+
+**`remoteImport` (remote-import)**
+Uploads the selected dump via `scp`, imports it on the server with
+`source .env && mysql`, clears remote Laravel caches via SSH, then removes
+the remote copy.
+
+**`listDatabases` (list)**
+Calls `find10LatestFiles` with optional environment filter, prints results to
+the terminal.
+
+### `bin/groups/database.js`
+CLI layer only. Wires the five Commander subcommands to the functions in
+`src/database.js`. No business logic.
+
+### `OPEN_QUESTIONS.md`
+Documents Q1 (deploy tool decision) and the exact files that will need updating
+once the answer is known.
+
+---
+
+## Design decisions
+
+- **`source .env` on the server** — the cleanest way to get DB credentials for
+  mysqldump without passing them from the developer's machine or hardcoding them.
+  Works for standard Laravel `.env` files. Edge cases (special chars in passwords)
+  are handled by quoting variables: `-u"$DB_USERNAME"`.
+- **Shell pipe for mysql import** — `docker exec -i` with stdin redirect requires
+  `sh -c "... < file"` rather than native spawn piping, for simplicity.
+- **Docker container naming** — `{APP_NAME}-db` for MySQL, `{APP_NAME}-app` for
+  the Laravel PHP container. These will be set by the Docker Compose stubs in a
+  future release.
+- **AMS mode preserved** — the `--ams` flag is wired through for filename
+  convention compatibility, even though AMS-specific database logic is minimal
+  for Laravel.