fix: make copy deploy symlink-aware and surface deploy errors

[ssx]

Description

The copy deploy strategy is not symlink-aware, and DeployManager silently swallows deploy failures outside debug mode. Together these cause Magento installs to end up with a partially or completely unpopulated setup/ directory (and other mapped dirs) with no error output.

Root cause

Copy::createDelegate() (dir-to-dir branch):

if (file_exists($destPath)) {
    $destPath .= DIRECTORY_SEPARATOR . basename($sourcePath);
}
mkdir($destPath, 0755, true);   // "mkdir(): File exists" for a dangling symlink

When a mapped destination is a symlink whose target does not currently exist (common with shared persistent storage, e.g. pub/media/custom_options -> /shared/pub/media/custom_options), file_exists() follows the link and reports the path as absent. mkdir() then runs against an existing link node and fails with mkdir(): File exists.

DeployManager::doDeploy() caught the resulting \ErrorException but only wrote it in debug mode, so the package's remaining mappings (including setup/) were skipped silently.

Fix

1. Copy::createDelegate() is symlink-aware — a pre-existing symlink at the destination (e.g. a shared-storage mount) is preserved instead of being clobbered or mkdir-ed over. A destination that exists but is not a directory (and is not a symlink) now throws an \ErrorException naming the exact path, rather than letting mkdir() emit a path-less warning.
2. DeployManager::doDeploy() hard-fails — a deploy error is no longer swallowed. It is re-thrown as a \RuntimeException naming the package, the underlying message, and the originating file:line, aborting the install with a non-zero exit. A broken/incomplete deploy means the application cannot run, so failing loudly is correct.

Legitimate shared-storage symlinks are preserved (not a failure); only genuine deploy errors abort.

Manual testing

On a clean magento/project-community-edition=2.4.8-p5 install (default copy strategy):

1. find setup -type f | wc -l → 566 (baseline).
2. ln -s /shared/pub/media/custom_options pub/media/custom_options (dangling target), then composer reinstall magento/magento2-base.
   • Before: setup/ empty/missing, no error printed; -vvv reveals mkdir(): File exists at Copy.php.
   • After: redeploy completes with no error, setup/ back to 566, and the symlink is preserved.

Coding standard

Verified clean under the Magento2 PHPCS standard (no silenced errors). The remaining DiscouragedFunction warnings on mkdir/is_dir/is_link/file_exists are pre-existing throughout this file and unavoidable here — Magento\Framework\Filesystem\DriverInterface is not available at Composer-plugin runtime.

Notes

Related upstream report filed at magento/magento2 issues.

[ssx]

This is a fix for the issue reported here: magento/magento2#40864

[ssx]

@magento I have signed the Magento Contributor Agreement

[ssx]

@magento-engcom-team is anyone alive that checks this repo?

[ssx]

@engcom-Delta @ahonc-adobe @engcom-Bravo @engcom-Charlie @engcom-Alfa @engcom-Echo @engcom-Golf @engcom-Dash