docs: add dump manager research notes

docs/research/admin-dump-manager-ui.md

@@ -0,0 +1,137 @@
+# Research: Administration UI for AeonDumpManager (list/create/delete SQL dumps)
+
+Target: Shopware 6.6 administration plugin development. Differences for 6.7 noted per section.
+
+## Summary / Recommendations
+
+- **Menu**: Register a module with `Shopware.Module.register()` and a `navigation` entry whose `parent` is an existing settings-area id (e.g. `sw-settings` or a dedicated top-level *is not allowed* for plugins — see §1). For a dev-tooling plugin like AeonDumpManager, nest under Settings rather than trying to create a first-level item; Shopware Store review explicitly rejects plugins that add first-level menu entries.
+- **Module structure**: One `module/aeon-dump-manager` folder with `index.js` (routes/navigation/snippets), a single list page component, no detail/create page needed as a separate route — a create action can be a button + modal on the list page since dumps aren't Shopware entities. Bind `sw-data-grid` directly to a plain JS array (`this.dumps`) returned from your own API, not an `EntityCollection`/`repository.search()` flow.
+- **Backend communication**: Write one custom PHP controller extending `AbstractController`, scoped with `#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]` (or `AdministrationRouteScope::ID`) under `/api/_action/aeon-dump-manager/...`, tagged as a service (`shopware.controller` context via `routes.xml`/`routes.php` auto-discovery). Pair it with a small JS `ApiService` subclass (`Shopware.Classes.ApiService`) registered via `Application.addServiceProvider`, injected into the component via `inject: ['aeonDumpManagerApiService']`. Do **not** rely on client-side ACL checks alone (`acl.can()` only hides UI) — do the real permission check server-side, e.g. via `AclRoleDefinition` privilege validation, since ACL in the admin can be bypassed by direct API calls.
+- **TypeScript**: There is no first-class "TypeScript for admin plugins" guide; official support is limited to extending the webpack build (`build/webpack.config.js`, pre-6.7) or Vite config (`vite.config.mts`, 6.7+) to add `ts-loader`/`@babel/preset-typescript`, and core is now written largely in TS internally. Unless the project already needs TS, skip it — plain JS with the existing Vue 2-options-API-via-compat conventions is the supported default and avoids one more moving build part for a small plugin.
+- **File size formatting**: Do not reimplement byte formatting — the admin core already ships `fileSize(bytes, locale)` under `Shopware.Utils.format.fileSize`. Reuse it directly in the grid column renderer.
+- **6.7**: Biggest relevant changes are the Vue 2 compat-layer removal (must be genuinely Vue 3 compatible components — no `$set`/`$delete`, watch `this.$…` internal API usage), Vuex→Pinia (`Shopware.State` → `Shopware.Store`, only relevant if you add a custom store), and Webpack→Vite (only relevant if you extend the build). None of this blocks writing the module against 6.6 now, provided the components avoid deprecated Vue 2-only patterns.
+
+---
+
+## 1. Admin menu registration
+
+A plugin adds an admin module (and its menu entry) via `Shopware.Module.register(moduleId, config)` called from `src/Resources/app/administration/src/module/<name>/index.js`, imported by `main.js`. The `navigation` property of the config is an array of navigation-entry objects; the documented fields are `id`, `label`, `path` (a dot-notation route id matching a `routes` entry), `icon`, `color`, `parent`, and `position` (numeric ordering). [Add Menu Entry — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html)
+
+**Important restriction**: plugin modules cannot add entries at the first level of the main menu — a `parent` pointing at an existing menu node (Shopware supports infinite nesting) is required. The Shopware Store plugin review process explicitly rejects plugins that create their own first-level menu entry. [Add Menu Entry — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html)
+
+**ACL-gated visibility**: a `navigation` entry (and individual `routes` entries via `meta.privilege`) can carry a `privilege` key so the menu item / route is hidden unless the logged-in admin user has that privilege — privileges are declared separately via `Shopware.Service('privileges').addPrivilegeMappingEntry(...)` in a module's `acl/index.js`. [Adding Permissions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.html)
+
+**Where to hook in for a dev-tooling plugin**: Shopware's own settings modules (e.g. `sw-settings`) are the conventional parent for administrative/operational tooling that isn't a merchandising concept (products, orders, etc.). Since AeonDumpManager already exposes a store-config panel via `config.xml` (per `CLAUDE.md`), placing the module's navigation entry as a child of the existing settings area is the natural, non-first-level location and matches the plugin's job (dev/ops tooling, not a customer-facing catalog feature).
+
+**6.7 differences**: The `Module.register` / navigation API itself is not called out as changed in the 6.7 upgrade materials found. The changes that *do* land in 6.7 and affect any admin module (menu module included) are:
+- Removal of the Vue 2 compatibility build — plugin components must be genuinely Vue-3-compatible (no `$set`/`$delete`, check `this.$…` internal Vue API usage, `sw-field` replaced by its successor components). [Vue 3 Upgrade guide — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue3.html), [Removing Vue Migration Build roadmap — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue-migration-build.html)
+- Vuex → Pinia: any plugin-registered Vuex store must move from `Shopware.State` to `Shopware.Store` (not applicable here unless AeonDumpManager adds its own store, which is not necessary for a dump list). [Vue 3 Upgrade guide — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue3.html)
+- Webpack → Vite for the admin build (see §4).
+
+No meteor-admin-sdk vs. core-plugin distinction is relevant here: `meteor-admin-sdk` (the "app extension SDK", formerly `admin-extension-sdk`) is the mechanism for **Shopware Apps** (no PHP backend, communicate over `postMessage`/iframe), not for a classic PHP+JS **plugin** like AeonDumpManager, which uses the core plugin administration extension mechanism documented above. This plugin is a PHP plugin (`shopware-platform-plugin`, confirmed by `CLAUDE.md`), so the core `Shopware.Module.register` path is the correct one, not the SDK.
+
+## 2. Building the admin UI module structure
+
+Conventional directory layout under `src/Resources/app/administration/src/`:
+
+```
+main.js                              # imports the module: import './module/aeon-dump-manager';
+module/aeon-dump-manager/
+  index.js                           # Shopware.Module.register(...) — routes, navigation, snippets
+  acl/index.js                       # addPrivilegeMappingEntry (optional but recommended)
+  snippet/
+    en-GB.json
+    de-DE.json
+  page/
+    aeon-dump-manager-list/
+      index.js                       # Shopware.Component.register(...)
+      aeon-dump-manager-list.html.twig
+```
+
+`index.js` registers routes (e.g. `list: { component: 'aeon-dump-manager-list', path: 'list' }`), the `navigation` array (§1), and `snippets` per locale. [Add Custom Module — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/module-component-management/add-custom-module.html), [Add Custom Route — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-custom-route.html)
+
+**List rendering — plain array, not `EntityCollection`**: `sw-data-grid` is documented and used with a plain array of plain objects assigned to component `data()`, not necessarily an entity repository result:
+
+```html
+<sw-data-grid :data-source="dataSource" :columns="columns"></sw-data-grid>
+```
+```js
+data() {
+    return {
+        dataSource: [ { id: 'uuid1', company: 'Wordify', name: 'Portia Jobson' }, ... ],
+        columns: [ { property: 'name', label: 'Name' }, { property: 'company', label: 'Company' } ]
+    };
+}
+```
+[Using the Data Grid Component — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.html)
+
+This is exactly the right fit for AeonDumpManager: dump files are filesystem entries, not DAL entities, so the list page's `data()` should hold the array returned by your custom API (§3) — each row `{ id/filename, createdAt, name, sizeBytes }` — with a `columns` config of `name`, a datetime column (format via existing Shopware date filter/util), and a size column whose `label` renders `Shopware.Utils.format.fileSize(row.sizeBytes)` (§5). Do not build an `EntityCollection` or wire a `repositoryFactory` for this list — that machinery is for DAL entities and would be pure overhead here.
+
+**Create/delete flow**: a "Create dump" `sw-button` triggers your API service's create call and reloads the list; per-row delete uses a row action (`sw-context-button`/action column) that opens a confirmation dialog before calling delete. Shopware's own standard confirmation component is `sw-confirm-modal` (added in 6.3.5.0 as the standard confirm-modal component for exactly this kind of "are you sure you want to delete" flow) — reuse it rather than hand-rolling a `sw-modal` yes/no dialog. [changelog: added-sw-confirm-modal.md — github.com/shopware/shopware](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-3-5-0/2021-01-06-added-sw-confirm-modal.md), [sw-confirm-modal — component-library.shopware.com](https://component-library.shopware.com/components/sw-confirm-modal)
+
+## 3. Frontend-to-backend communication
+
+**JS side**: define a custom API service class extending `Shopware.Classes.ApiService`, register it through `Shopware.Application.addServiceProvider('aeonDumpManagerApiService', (container) => { const initContainer = Application.getContainer('init'); return new AeonDumpManagerApiService(initContainer.httpClient, container.loginService); })`, and inject it into components with `inject: ['aeonDumpManagerApiService']` → available as `this.aeonDumpManagerApiService`. The base class supplies `getBasicHeaders()` (auth token handling) and `ApiService.handleResponse()` for uniform error handling; a GET/POST/DELETE call is `this.httpClient.get(route, { headers: this.getBasicHeaders() })` etc. [Adding Services — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/add-custom-service.html), [Making API Requests — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/services-utilities/making-api-requests.html)
+
+**PHP side**: create a controller extending `AbstractController`, scoped to the admin/API domain via the class-level attribute
+
+```php
+#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]
+class DumpController extends AbstractController
+{
+    #[Route(
+        path: '/api/_action/aeon-dump-manager/dumps',
+        name: 'api.action.aeon_dump_manager.dumps.list',
+        methods: ['GET']
+    )]
+    public function list(Context $context): JsonResponse { ... }
+}
+```
+
+This mirrors the core `ApiController`'s own pattern (`#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]` at class level, with `/api/_action/...` action routes at method level, e.g. its `clone` action at `/api/_action/clone/{entity}/{id}`). [ApiController.php — github.com/shopware/core (trunk)](https://github.com/shopware/core/blob/trunk/Framework/Api/Controller/ApiController.php); Administration-specific controllers use `AdministrationRouteScope::ID` from `Shopware\Administration\Framework\Routing\AdministrationRouteScope` instead when the endpoint is administration-only rather than general Admin API. [AdministrationController.php — github.com/shopware/administration (trunk)](https://github.com/shopware/administration/blob/trunk/Controller/AdministrationController.php)
+
+Controller discovery uses the plugin's `src/Resources/config/routes.php` (or `routes.xml`) importing `../../Controller/*Controller.php` via the `attribute` type loader — the same auto-discovery mechanism documented for storefront controllers, generalized to any controller directory. [Add Custom Controller — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/storefront/add-custom-controller.html)
+
+**ACL/authorization**: All admin and API routes are authentication-protected by default (bearer token from the admin's own OAuth session, attached automatically by `getBasicHeaders()`/`loginService` on the JS side — no separate manual OAuth dance needed in the component code). [UPGRADE-6.1.md — github.com/shopware/shopware](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.1.md) Client-side privilege checks (`this.acl.can('aeon_dump_manager.viewer')`, `v-if="acl.can(...)"`) only toggle UI visibility and are documented as bypassable via direct API calls — the actual authorization must be enforced in the controller itself, e.g. by validating against `AclRoleDefinition` privilege constants the way `ApiController::clone()` does (`$this->validateAclPermissions($context, $definition, AclRoleDefinition::PRIVILEGE_CREATE)`, throwing `ApiException::missingPrivileges()` on failure), or via the `#[Acl(...)]` attribute mechanism that superseded the deprecated `@Acl` annotation for controller-level privilege gating. [Adding Permissions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.html), [ApiController.php — github.com/shopware/core (trunk)](https://github.com/shopware/core/blob/trunk/Framework/Api/Controller/ApiController.php), [ADR: controller-configuration-route-defaults — developer.shopware.com](https://developer.shopware.com/docs/resources/references/adr/2022-02-09-controller-configuration-route-defaults.html)
+
+For AeonDumpManager, declare a plugin-specific privilege set (e.g. `aeon_dump_manager.viewer` / `.creator` / `.deleter`) via `acl/index.js` (`addPrivilegeMappingEntry`), gate the menu/routes with it client-side for UX, and re-check an equivalent permission (or at minimum require an authenticated admin session, which is already default) server-side before actually running a `mysqldump`/file-delete operation — these are filesystem/process-level actions, so being defensive here matters more than for a typical read-only entity list.
+
+*Gap note*: the official docs found do not show a first-party doc page titled specifically "add custom admin API route" with a full worked PHP example (the closest, `add-custom-route.html`, only covers the **Vue Router** side, i.e. `routes:` in `Module.register`, not the PHP controller) — the PHP-side pattern above is instead verified directly against the shipped `ApiController`/`AdministrationController` source in `shopware/core` and `shopware/administration`, which is authoritative but means there's no single canonical doc page combining both halves end-to-end for a plugin.
+
+## 4. TypeScript setup for Shopware 6 administration
+
+There is no dedicated "TypeScript for administration plugins" guide among the fetched official pages. What exists officially:
+
+- **Build extension mechanism (6.6 and earlier)**: a plugin can provide `src/Resources/app/administration/build/webpack.config.js` exporting a function that returns webpack config overrides — this is the documented, supported extension point (`Extending Webpack`). [Extending Webpack — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/extending-webpack.html) That page itself contains **no TypeScript-specific guidance** (no `.ts`/`.tsx`, `ts-loader`, or `tsconfig` mention) — adding `ts-loader` or `@babel/preset-typescript` there is a community pattern layered on top of a documented extension point, not something the official page walks through.
+- **6.7: Webpack → Vite**. Per the roadmap doc, plugins are only affected if they currently ship a custom `webpack.config.js`; those must migrate to a `vite.config.mts` file (note the `.mts` extension — TypeScript by convention for the config file itself) under `.../administration/src/`, and delete the old webpack config/dependencies. [Future Development Roadmap: Changing from Webpack to Vite — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/system-updates/vite.html)
+- Shopware's own administration source has increasingly moved to `.ts`/`.vue`+TS internally (e.g. core factory files like `async-component.factory.ts` in `shopware/shopware` trunk), i.e. the *core team's own code* is TypeScript, but this is not the same as an officially documented, supported path for **plugin** authors to write their own module in TypeScript out of the box.
+
+**Recommendation for AeonDumpManager**: skip TypeScript. Per the ponytail ladder, there's no existing TS need in this repo (PHP `^8.1` project per `CLAUDE.md`, no existing frontend TS tooling), and the admin plugin surface here is small (one list page, one service). Adding a custom `webpack.config.js`/`vite.config.mts` + `ts-loader`/tsconfig just to type a handful of small Vue components is speculative infrastructure for a plugin whose entire admin footprint is one grid and one API service; plain JS following the documented module/service conventions is both fully supported and the shorter path. Revisit only if the plugin's admin surface grows substantially or the team adopts TS project-wide.
+
+## 5. File size formatting
+
+Shopware's administration core already ships a byte-formatting helper — do not reimplement it. It's documented in the Utils reference (`Shopware.Utils.format.fileSize`, described as "Formats a number of bytes to a string with a unit") [Utils Reference — developer.shopware.com](https://developer.shopware.com/docs/resources/references/administration-reference/utils.html), and its exact implementation in the `shopware/shopware` monorepo (Administration bundle) is:
+
+```ts
+// src/Administration/Resources/app/administration/src/core/service/utils/format.utils.ts (shopware/shopware, trunk)
+export function fileSize(bytes: number, locale = 'de-DE'): string {
+    const denominator = 1024;
+    const units = ['B', 'KB', 'MB', 'GB'];
+
+    let result = Number.parseInt(String(bytes), 10);
+    let i = 0;
+
+    for (; i < units.length; i += 1) {
+        const currentResult = result / denominator;
+        if (currentResult < 0.9) break;
+        result = currentResult;
+    }
+
+    return `${result.toFixed(2).toLocaleString(locale)}${units[i]}`;
+}
+```
+[format.utils.ts — github.com/shopware/shopware (trunk)](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/service/utils/format.utils.ts)
+
+Usage in a plugin component: `Shopware.Utils.format.fileSize(row.sizeBytes)` (accessed via the global `Shopware.Utils` object per the "Using utility functions" guide). [Using utility functions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/using-utils.html) This directly satisfies the "MB/GB human-readable size column" requirement with zero custom code — pass the dump file's byte size straight through it in the `sw-data-grid` column renderer/slot.
+
+Note it only goes up to `GB` (no `TB` step) and defaults to `de-DE` locale formatting unless a locale is passed — pass the admin's current locale (`Shopware.State.get('session').currentLocale` in 6.6, or its `Shopware.Store` equivalent post-Pinia-migration in 6.7) if locale-correct number formatting matters, otherwise the default is fine for dump files (unlikely to exceed a few GB).

docs/research/dump-binary-config.md

@@ -0,0 +1,178 @@
+# Research: Admin-configurable dump binary path — is it an attack surface?
+
+Target: `src/Service/DumpBinaryLocator.php`'s `dumpBinaryPath` config field and how it feeds
+`src/Service/DumpService.php::buildProcess()`.
+
+## Summary / Recommendation
+
+- **Not a shell-injection vector.** `Process` built from an array (`new Process([$binary, ...])`)
+  never goes through a shell — PHP's `proc_open()` execs the array directly, so whatever string sits
+  in `$binary` is passed straight to `exec()` as the program path. There's no shell metacharacter
+  parsing to exploit via that string's *content* (§1).
+- **The real concern is authorization scope, not injection**: `dumpBinaryPath` is whatever
+  `SystemConfigService::getString()` returns, gated only by Shopware's `system_config:read`/`:update`
+  ACL privilege — a privilege that can be granted independently of shell/SSH access to the box. A
+  role with system-config write access but *no* shell access can currently point this field at any
+  executable already reachable on disk and have the plugin run it as `www-data`. That's a real,
+  if narrow, privilege-escalation surface for this one specific plugin — not a "trusts itself" non-issue,
+  because system-config-write and filesystem/shell access are not the same trust tier in Shopware's ACL
+  model (§1).
+- **Recommendation for this plugin**: drop `dumpBinaryPath` (arbitrary absolute path) in favor of a
+  `dumpBinaryName` override, resolved through `ExecutableFinder::find($name)` exactly like the
+  auto-detected default — never returned as a raw path straight from config. This closes the
+  arbitrary-path surface (an admin can only ever get a `PATH`-resolved binary, never point at
+  `/etc/shadow`-adjacent binaries or an arbitrarily uploaded file) while still covering the one
+  legitimate reason to override at all: a distro/environment that names the client something
+  nonstandard. Given dockware ships `mysqldump` on `PATH` already (confirmed in the prior research doc,
+  `.scratch/admin-dump-manager/issues/01-detect-dump-binary.md` §3), the override will sit unused in
+  the common case — which is fine, it's a two-line fallback, not new infrastructure (§2, §3).
+- An env-var override was considered and rejected as the *primary* mechanism for this plugin — it's
+  the right shape for ops-owned infra config, but this plugin already has a config-field UI and
+  `SystemConfigService` wired in for `maxDumps`/`retantionDays`; adding a second override channel
+  (env var) alongside the DB-stored one is more moving parts than the problem needs (§2, §3).
+
+## 1. Is there a real security concern?
+
+`DumpService::buildProcess()` builds the command as an array:
+
+```php
+$command = [$binary, '--single-transaction', '--quick', '-h', ..., '-u', ..., $dbname];
+$process = new Process($command, null, ['MYSQL_PWD' => $password]);
+```
+
+Symfony's own docs are explicit that array form is the safe form and *why*:
+
+> "Using an array of arguments is the recommended way to define commands. This saves you from any
+> escaping and allows sending signals seamlessly." — and contrasts it with `Process::fromShellCommandline()`,
+> where "it becomes your responsibility to deal with escaping and portability."
+> [Symfony Process component docs](https://symfony.com/doc/current/components/process.html)
+
+Mechanically: `Process` (array constructor) hands the array straight to PHP's `proc_open()`, which —
+given an array `command` argument — execs the binary directly (no `/bin/sh -c` wrapping), per PHP's
+own `proc_open()` behavior for array-form commands (bypasses the shell entirely on Linux since PHP
+7.4). So `$binary`'s *string content* can't be used to inject additional shell commands (no `;`, `` ` ``,
+`$()`, pipes, etc. get interpreted) — the entire "shell injection via a crafted path string" concern
+the user was worried about does not apply to this code as written. This holds **regardless of whether
+`$binary` comes from `ExecutableFinder::find()` or directly from `SystemConfigService::getString()`** —
+both are just strings landing in the same array slot.
+
+**So what is the actual concern?** Not injection — authorization scope. `dumpBinaryPath` is read via:
+
+```php
+$configuredPath = $this->systemConfigService->getString('AeonDumpManager.config.dumpBinaryPath');
+if ($configuredPath !== '') {
+    return $configuredPath;
+}
+```
+
+This value is *whatever an admin with write access to this plugin's store-config typed*, used
+**verbatim** as the program to exec — no `is_executable()` check, no restriction to a known directory,
+no validation at all beyond non-empty. Setting it, in Shopware's ACL model, requires the
+`system_config:read`/`system_config:update` privilege (or a role with `administration` access broadly).
+That privilege is not the same tier as "has a shell on the container" — Shopware routinely grants
+narrower admin roles (e.g. a merchandising-ops role scoped to a handful of modules including this
+plugin's settings card) without granting SSH/exec access to the underlying host. For *this specific
+field*, anyone who can write plugin config can make the plugin exec an arbitrary path on disk as
+`www-data` — e.g. pointing it at any already-present script/binary, or (in a shared-hosting-style setup)
+a path they can write to via some unrelated upload feature. That's a real, if narrow and
+low-severity-in-practice (dev-tooling plugin, dockware-only target per `CLAUDE.md`), escalation: it
+turns "can edit this plugin's config" into "can execute an arbitrary path as the PHP process user,"
+which is a strictly larger capability than the plugin should need to grant. It is not an
+*unauthenticated-attacker* vector — Shopware's admin panel is authenticated and this requires a
+specific privilege — but "only a privileged admin can trigger it" doesn't make it a non-issue when the
+privilege in question (system-config write) is deliberately a narrower grant than shell access in
+Shopware's own permission model.
+
+## 2. Alternatives, evaluated
+
+### a. Drop the field entirely, `ExecutableFinder::find()` only, fail loudly
+
+Simplest option. `ExecutableFinder::find($name)` (confirmed against `symfony/process` source,
+`ExecutableFinder.php`, current branch) searches, in order:
+
+1. Directories from the `PATH` env var (`getenv('PATH')`, or `Path` on Windows), merged with any
+   `$extraDirs` argument.
+2. For each directory, `is_file($dir/$name$suffix) && is_executable(...)` (suffix loop is a no-op on
+   Linux; Windows-only `PATHEXT` extensions).
+3. As a last resort on non-Windows, shells out to `command -v -- $name` (via `escapeshellarg()`) —
+   this is the *only* place `ExecutableFinder` itself touches a shell, and it shell-escapes the binary
+   *name* being searched for, not a path being executed.
+
+[`ExecutableFinder.php` — symfony/process, GitHub](https://github.com/symfony/process/blob/7.1/ExecutableFinder.php)
+
+Pro: zero config-surface, nothing to misconfigure. Con: on the (rare, per the linked prior research)
+case where `mysqldump`/`mariadb-dump` genuinely isn't on `PATH` for `www-data`, there's no way to
+recover without an env var or code change — for a plugin whose whole job is producing dumps, a hard
+dependency on `PATH` composition an admin can't influence from the plugin's own UI is a mildly awkward
+dead end.
+
+### b. Binary *name* override (`dumpBinaryName`), still resolved via `ExecutableFinder::find()`
+
+```php
+$configuredName = $this->systemConfigService->getString('AeonDumpManager.config.dumpBinaryName');
+$binaryNames = $configuredName !== ''
+    ? [$configuredName]
+    : ($this->isMariaDb() ? ['mariadb-dump', 'mysqldump'] : ['mysqldump']);
+
+foreach ($binaryNames as $binaryName) {
+    $path = $this->executableFinder->find($binaryName);
+    if ($path !== null) {
+        return $path;
+    }
+}
+```
+
+This is a ~3-line diff from the current code — same shape, same loop, just the value coming out of
+config is *always* passed through `find()` rather than ever being returned directly. Every path
+`buildProcess()` can end up executing is a `PATH`-resolved, `is_executable()`-checked file — an admin
+can redirect *which name* gets looked up (covers a renamed/nonstandard binary on an unusual
+distro/environment) but can never point the plugin at an arbitrary filesystem path outside `PATH`.
+This directly closes the gap in §1 while preserving the one legitimate override use case the original
+field existed for.
+
+### c. Environment variable override (`getenv('AEON_DUMP_BINARY_PATH')` or similar)
+
+Moves the override from "whoever has Shopware admin-config write access" to "whoever controls the
+container/deployment env" (ops/devops, via `docker-compose.yml`, `.env`, or the container's process
+environment) — a meaningfully different, generally higher, trust tier, and consistent with how
+`docker-compose.yml` already configures this repo's dev container (`SSH_USER`/`SSH_PWD` env vars per
+`CLAUDE.md`). This is a legitimate pattern in general. For *this* plugin specifically it's more
+machinery than the problem justifies: it adds a second config source (env var) next to the existing
+`SystemConfigService`-backed admin UI field, for a value that (per §3) essentially never needs
+overriding in the actual target environment (dockware). It's the right tool if this were, say, a
+plugin deployed across heterogeneous customer infrastructure where ops teams routinely differ from
+Shopware-admin teams — not proportionate for a project-local dev-tooling plugin with one target
+container image.
+
+## 3. Recommendation for this plugin
+
+Use **(b)** — replace `dumpBinaryPath` (text, absolute path) with `dumpBinaryName` (text, binary name,
+default empty → falls back to the existing MariaDB/MySQL name-detection list) in
+`src/Resources/config/config.xml`, and change `DumpBinaryLocator::locate()` to prepend the configured
+name (if any) to the existing `$binaryNames` loop instead of short-circuiting with a raw path. This is
+sized right for a dev-tooling plugin that per the prior research (`.scratch/.../01-detect-dump-binary.md`
+§3) targets dockware, where `mysqldump` is already confirmed present on `PATH` — the override becomes
+a rarely-touched escape hatch rather than the primary mechanism, and it removes the one place in this
+plugin where admin-supplied config was executed as a program path with no validation. Skip (c)/env-var:
+it solves a deployment-heterogeneity problem this single-container plugin doesn't have, and would be a
+second override mechanism doing the same job as the config field, for no concrete gain here. Skip
+(a)/no-override-at-all: it's the smallest diff but removes a genuine, if narrow, recovery path for a
+`PATH`-less edge case at effectively zero cost to keep (b) instead — (b) is one loop-entry away from (a)
+and already sits inside the existing `foreach ($binaryNames as $binaryName)` structure in
+`DumpBinaryLocator::locate()`.
+
+No code changes were made as part of this research task — see
+`src/Service/DumpBinaryLocator.php`, `src/Service/DumpService.php::buildProcess()`, and
+`src/Resources/config/config.xml` for the current state to build (b) against.
+
+## Sources
+
+- [Symfony Process component docs — command arrays vs `fromShellCommandline()`](https://symfony.com/doc/current/components/process.html)
+- [`ExecutableFinder.php` — symfony/process, GitHub (7.1 branch)](https://github.com/symfony/process/blob/7.1/ExecutableFinder.php)
+- PHP manual, `proc_open()` — array-form `command` execs directly without a shell wrapper (documented
+  behavior since PHP 7.4 for the array-command form on non-Windows).
+- `src/Service/DumpBinaryLocator.php`, `src/Service/DumpService.php` (this repo, current state).
+- `.scratch/admin-dump-manager/issues/01-detect-dump-binary.md` (prior locked research: dockware ships
+  `mysqldump` on `PATH`, MariaDB binary-naming history, `ExecutableFinder` recommendation).
+- `.scratch/dump-manager-implementation-spec/spec.md` §0, §2.2 (locked design context for the
+  `dumpBinaryPath` field and `DumpBinaryLocator` shape being reconsidered here).