AeonDumpManager/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

AeonDumpManager is a Shopware 6 plugin (`shopware-platform-plugin`) that manages database dumps for
Shopware 6 development environments. It lists, creates, and deletes gzip-compressed `mysqldump`/
`mariadb-dump` SQL dumps, both from a Settings-page admin UI (async creation with a polling progress
bar) and via `aeon:dump:{list,create,remove}` console commands (sync creation). Design decisions and
the full build spec live under `.scratch/admin-dump-manager/` and `.scratch/dump-manager-implementation-spec/`
(Wayfinder maps) — consult those before changing the dump-creation/retention/ACL behavior.

- Plugin bootstrap class: `src/AeonDumpManager.php` (extends `Shopware\Core\Framework\Plugin`) — this
  is the entry point Shopware calls for install/uninstall/activate/deactivate/update lifecycle hooks.
- Plugin class name is wired via `composer.json` → `extra.shopware-plugin-class`.
- Services are registered manually in `src/Resources/config/services.yaml` (Symfony DI, YAML format,
  autowiring is not configured — every new service/command/task must be added here explicitly with
  its tag, e.g. `console.command` or `shopware.scheduled.task`).
- Plugin store-config UI fields (e.g. `maxDumps`, `retantionDays`) are defined in
  `src/Resources/config/config.xml` and read at runtime via Shopware's SystemConfigService.
- `src/Resources/app/administration/` holds the admin UI module (Vue-based Shopware Administration
  extension). The `aeon-dump-manager` module (`src/module/aeon-dump-manager/`) provides the list page
  (`page/aeon-dump-manager-list`), en-GB/de-DE snippets and ACL privilege roles (`acl/`: `viewer`,
  `creator`, `deleter`); `src/service/dump-api.service.ts` is the client for the dump API routes.

## Running the plugin

There is no standalone runtime — this plugin only runs inside a Shopware 6 instance. Local dev uses
`docker-compose.yml`, which mounts the repo into a `dockware/shopware` container at
`custom/plugins/AeonDumpManager`:

```bash
docker compose up -d
```

Shop/Admin/Adminer are all served on port 80/443; SSH into the container on port 22
(`SSH_USER=shopware` / `SSH_PWD=shopware`); admin-watcher and storefront-watcher proxies are exposed
on 8888/9998/9999 for `bin/build-administration.sh --watch` style workflows run inside the container.

Plugin install/activate must be done through Shopware's own tooling inside the container (e.g.
`bin/console plugin:refresh`, `bin/console plugin:install --activate AeonDumpManager`) — there is no
composer script for this in this repo.

The container's internal processes run as uid/gid 33 (`www-data`). The repo directory on the host is
group-owned by that group with setgid bit set (`chgrp -R 33` + `chmod g+s`), so both the container and
host users in group 33 can write without ownership fights.

## Tests

PHPUnit, bootstrapped through Shopware's own `TestBootstrapper` (`tests/TestBootstrap.php`), which
activates this plugin inside a real Shopware kernel for the test run (`KERNEL_CLASS` is set to
`Shopware\Core\Kernel` in `phpunit.xml`). This means tests require a working Shopware installation/DB
to bootstrap against — they are not runnable as an isolated PHP package.

In CI (`phpunit` job) the latest Shopware version allowed by the plugin's `require.shopware/core` constraint
is resolved with Composer. The prepared project (`composer create-project` + phpunit, then `system:install`
into `shopware_test` on a MariaDB 10.11 service) plus a SQL dump of the installed database are cached under
a key that contains that version, so a new Shopware release invalidates the cache. On a hit the dump is restored instead of reinstalling; the plugin
is then copied into `custom/plugins` and the bootstrapper only activates it.

```bash
vendor/bin/phpunit                              # full suite
vendor/bin/phpunit --filter TestClassName        # single test class
vendor/bin/phpunit tests/SomeTest.php            # single file
```

## Dependencies

- PHP `^8.2`, `shopware/core` `~6.7.0` (from `composer.json`); `phpunit/phpunit` `^10.0` as the only
  dev dependency.
- PSR-4 autoload: `AeonDumpManager\` → `src/`, `AeonDumpManager\Tests\` → `tests/`.

## CI / release pipeline

Gitea workflows in `.gitea/`, plugin-agnostic (name/version come from `composer.json`). `shopware-cli`
runs from its official Docker image, intentionally unpinned (`latest`): a red build after a CLI release
means fix the config.

- `workflows/plugin-checks.yml` (PRs into `main`) has three jobs: `version-changelog` (the
  `composer.json` version must be greater than the latest published Gitea release and have a matching
  `## [x.y.z]` CHANGELOG heading), `package`
  (shared composite action `actions/package`: `shopware-cli extension package`, `extension validate` on
  the zip, `scripts/ci/assert-built-assets.sh`), and `phpunit`. The package job caches the tested zip
  keyed by the commit's tree hash.
- `workflows/release.yml` (push to `main`, serialized; every step is idempotent so a failed run can simply be re-run): reuses the
  cached zip when the tree hash matches (else packages again, always re-validates), creates the Gitea
  release + tag via API with the zip as asset, publishes a root-level repack of the zip to the Composer registry
  (Gitea requires `composer.json` at the zip root), then links the
  package to the repo. Uses `RELEASE_TOKEN`.
- Required checks on `main` (`plugin-checks / version-changelog|package|phpunit (pull_request)`) are set
  once with `scripts/protect-main.sh` (`tea api`). Build excludes/validation live in
  `.config/shopware-extension.yml`. Background: `docs/spec/shopware-guideline-compliance.md`.

## Adding functionality

- New console commands go in `src/Command/`, new scheduled tasks in `src/ScheduledTask/` — both must
  be registered in `src/Resources/config/services.yaml` with the appropriate tag or Shopware will not
  discover them.
- Scheduled tasks need a matching handler (tagged `messenger.message_handler`) to actually run; a bare
  `ScheduledTask` subclass like `ExampleTask` only defines the schedule, not the behavior.