From efc4d1b52618177a01644c4e3366b170e8db68be Mon Sep 17 00:00:00 2001
From: Thomas Hauschild <7961978+Morgy93@users.noreply.github.com>
Date: Tue, 7 Jul 2026 13:36:44 +0200
Subject: [PATCH 1/2] feat: add template override command

---
 docs/commands_reference.md                    |  45 ++
 .../Command/Template/OverrideCommand.php      | 432 ++++++++++++++++++
 src/Model/TemplateReference.php               |  51 +++
 src/Service/TemplateOverride/AreaEmulator.php |  53 +++
 .../TemplateOverride/CompatModuleResolver.php |  91 ++++
 .../TemplateOverride/TemplateCopier.php       |  39 ++
 .../TemplateFallbackResolver.php              | 132 ++++++
 .../TemplateOverride/TemplatePathParser.php   | 289 ++++++++++++
 src/etc/di.xml                                |   2 +
 .../Command/Template/OverrideCommandTest.php  | 317 +++++++++++++
 tests/Unit/Model/TemplateReferenceTest.php    |  26 ++
 .../TemplateOverride/AreaEmulatorTest.php     |  52 +++
 .../CompatModuleResolverTest.php              |  82 ++++
 .../FakeCompatModuleRegistry.php              |  41 ++
 .../Service/TemplateOverride/FakeTheme.php    |  59 +++
 .../TemplateOverride/TemplateCopierTest.php   |  47 ++
 .../TemplateFallbackResolverTest.php          | 163 +++++++
 .../TemplatePathParserTest.php                | 281 ++++++++++++
 18 files changed, 2202 insertions(+)
 create mode 100644 src/Console/Command/Template/OverrideCommand.php
 create mode 100644 src/Model/TemplateReference.php
 create mode 100644 src/Service/TemplateOverride/AreaEmulator.php
 create mode 100644 src/Service/TemplateOverride/CompatModuleResolver.php
 create mode 100644 src/Service/TemplateOverride/TemplateCopier.php
 create mode 100644 src/Service/TemplateOverride/TemplateFallbackResolver.php
 create mode 100644 src/Service/TemplateOverride/TemplatePathParser.php
 create mode 100644 tests/Unit/Console/Command/Template/OverrideCommandTest.php
 create mode 100644 tests/Unit/Model/TemplateReferenceTest.php
 create mode 100644 tests/Unit/Service/TemplateOverride/AreaEmulatorTest.php
 create mode 100644 tests/Unit/Service/TemplateOverride/CompatModuleResolverTest.php
 create mode 100644 tests/Unit/Service/TemplateOverride/FakeCompatModuleRegistry.php
 create mode 100644 tests/Unit/Service/TemplateOverride/FakeTheme.php
 create mode 100644 tests/Unit/Service/TemplateOverride/TemplateCopierTest.php
 create mode 100644 tests/Unit/Service/TemplateOverride/TemplateFallbackResolverTest.php
 create mode 100644 tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php

diff --git a/docs/commands_reference.md b/docs/commands_reference.md
index 118a1f5a..69b1856c 100644
--- a/docs/commands_reference.md
+++ b/docs/commands_reference.md
@@ -11,6 +11,7 @@ Complete reference of all CLI commands provided by the MageForge module.
 | **Theme**  | `mageforge:theme:watch`              | Watch theme files and auto-rebuild                  | `frontend:watch` |
 | **Theme**  | `mageforge:theme:clean`              | Clean static files and cache directories            | `frontend:clean` |
 | **Theme**  | `mageforge:theme:inspector`          | Manage Frontend Inspector (enable/disable/status)   | —                |
+| **Template** | `mageforge:template:override`      | Copy a module template into a theme (override)      | `template:override` |
 | **Hyvä**   | `mageforge:hyva:tokens`              | Generate Hyvä design tokens                         | `hyva:tokens`    |
 | **Hyvä**   | `mageforge:hyva:compatibility:check` | Check modules for Hyvä compatibility issues         | `hyva:check`     |
 | **System** | `mageforge:system:version`           | Show current and latest module version              | `system:version` |
@@ -124,6 +125,49 @@ bin/magento mageforge:theme:inspector status
 
 ---
 
+## Template Commands
+
+### `mageforge:template:override`
+
+Copies a module template into a theme as an override, following Magento's view file fallback
+logic. The command resolves both the correct source file and the correct target directory for
+you — including the tricky cases where Hyvä compatibility modules ship the template that is
+actually rendered.
+
+```bash
+bin/magento mageforge:template:override <template> --theme <theme-code>
+bin/magento mageforge:template:override 'Magento_Catalog::product/view/details.phtml' --theme Vendor/theme
+bin/magento mageforge:template:override vendor/magento/module-catalog/view/frontend/templates/product/view/details.phtml -t Vendor/theme
+```
+
+**Arguments:**
+
+- `template` — The template to override. Accepts the `Module_Name::path/to/template.phtml`
+  notation or a file path (absolute, or relative to the Magento root / current directory).
+  File paths may point into a module's `view/<area>/templates` directory, a Hyvä compat
+  module, or another theme's override directory.
+
+**Options:**
+
+- `-t, --theme=VALUE` — Target theme code (format: `Vendor/theme`). If omitted, an interactive prompt appears.
+- `--dry-run` — Show source, target, and the full fallback search order without copying.
+- `-f, --force` — Replace an existing override with the next file in the fallback chain
+  (useful to reset an override to the original template).
+
+**Behavior:**
+
+- Uses Magento's own fallback rule (`RulePool`) with the frontend area DI configuration
+  loaded, so plugins like Hyvä's compat module fallback are honored.
+- Hyvä compat module templates are copied from the compat module (the file actually
+  rendered), but the override is placed under the **original** module's directory name,
+  e.g. `<theme>/Mollie_Payment/templates/...` — exactly where Magento looks for it.
+- After copying, the command re-resolves the template to verify the new override wins and
+  cleans the relevant caches (`full_page`, `block_html`, `layout`, `translate`).
+- If the template is already overridden in the target theme, nothing is copied unless
+  `--force` is given.
+
+---
+
 ## Hyvä Commands
 
 ### `mageforge:hyva:tokens`
@@ -210,6 +254,7 @@ mageforge:theme:build         → Build theme assets
 mageforge:theme:watch         → Watch & auto-rebuild
 mageforge:theme:clean         → Clean static files
 mageforge:theme:inspector     → Manage inspector tool
+mageforge:template:override   → Copy module template into a theme
 mageforge:hyva:tokens         → Generate Hyvä design tokens
 mageforge:hyva:compatibility:check → Check Hyvä compatibility
 mageforge:system:version      → Show module version
diff --git a/src/Console/Command/Template/OverrideCommand.php b/src/Console/Command/Template/OverrideCommand.php
new file mode 100644
index 00000000..e805f84e
--- /dev/null
+++ b/src/Console/Command/Template/OverrideCommand.php
@@ -0,0 +1,432 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Console\Command\Template;
+
+use Laravel\Prompts\SearchPrompt;
+use Laravel\Prompts\TextPrompt;
+use Magento\Framework\App\Area;
+use Magento\Framework\App\Filesystem\DirectoryList;
+use Magento\Framework\Console\Cli;
+use Magento\Framework\View\Design\ThemeInterface;
+use OpenForgeProject\MageForge\Console\Command\AbstractCommand;
+use OpenForgeProject\MageForge\Model\ThemeList;
+use OpenForgeProject\MageForge\Service\CacheCleaner;
+use OpenForgeProject\MageForge\Service\TemplateOverride\AreaEmulator;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateCopier;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateFallbackResolver;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplatePathParser;
+use OpenForgeProject\MageForge\Service\ThemeSuggester;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Command that copies a module template into a theme as an override
+ *
+ * The override location is derived from Magento's own view file fallback rule, so plugins
+ * like Hyvä's compat module fallback are honored and the copied file is guaranteed to be
+ * picked up by Magento's template resolution.
+ */
+class OverrideCommand extends AbstractCommand
+{
+    /**
+     * @param ThemeList $themeList
+     * @param ThemeSuggester $themeSuggester
+     * @param TemplatePathParser $templatePathParser
+     * @param TemplateFallbackResolver $fallbackResolver
+     * @param TemplateCopier $templateCopier
+     * @param AreaEmulator $areaEmulator
+     * @param CacheCleaner $cacheCleaner
+     * @param DirectoryList $directoryList
+     */
+    public function __construct(
+        private readonly ThemeList $themeList,
+        private readonly ThemeSuggester $themeSuggester,
+        private readonly TemplatePathParser $templatePathParser,
+        private readonly TemplateFallbackResolver $fallbackResolver,
+        private readonly TemplateCopier $templateCopier,
+        private readonly AreaEmulator $areaEmulator,
+        private readonly CacheCleaner $cacheCleaner,
+        private readonly DirectoryList $directoryList,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * Configure command
+     *
+     * @return void
+     */
+    protected function configure(): void
+    {
+        $this
+            ->setName($this->getCommandName('template', 'override'))
+            ->setDescription('Copies a module template into a theme, following Magento\'s fallback logic')
+            ->addArgument(
+                'template',
+                InputArgument::OPTIONAL,
+                'Template to override (Module_Name::path/to/template.phtml or a file path)',
+            )
+            ->addOption('theme', 't', InputOption::VALUE_REQUIRED, 'Target theme code (format: Vendor/theme)')
+            ->addOption(
+                'dry-run',
+                null,
+                InputOption::VALUE_NONE,
+                'Only show source, target and fallback order without copying',
+            )
+            ->addOption(
+                'force',
+                'f',
+                InputOption::VALUE_NONE,
+                'Replace an existing override with the next file in the fallback chain',
+            )
+            ->setAliases(['template:override']);
+    }
+
+    /**
+     * Execute command
+     *
+     * @param InputInterface $input
+     * @param OutputInterface $output
+     * @return int
+     */
+    protected function executeCommand(InputInterface $input, OutputInterface $output): int
+    {
+        $isDryRun = (bool) $input->getOption('dry-run');
+        $isForce = (bool) $input->getOption('force');
+
+        $frontendThemes = $this->getFrontendThemes();
+        if ($frontendThemes === []) {
+            $this->io->warning('No frontend themes found.');
+            return Cli::RETURN_SUCCESS;
+        }
+
+        $templateInput = $this->resolveTemplateInput($input, $output);
+        if ($templateInput === null) {
+            $this->displayUsage();
+            return Cli::RETURN_SUCCESS;
+        }
+
+        /** @var string|null $themeOption */
+        $themeOption = $input->getOption('theme');
+        $theme = $this->resolveTheme($themeOption, $frontendThemes, $output);
+        if ($theme === null) {
+            return $themeOption === null || $themeOption === '' ? Cli::RETURN_SUCCESS : Cli::RETURN_FAILURE;
+        }
+
+        // Load the theme area's DI configuration so fallback plugins (e.g. Hyvä compat) apply
+        $this->areaEmulator->emulate($theme->getArea());
+
+        $reference = $this->templatePathParser->parse($templateInput);
+        $templatePath = $reference->getTemplatePath();
+
+        $fallbackDirs = $this->fallbackResolver->getFallbackDirs($reference, $theme);
+        if ($fallbackDirs === []) {
+            $this->io->error(sprintf('No fallback directories found for %s.', $reference->getTemplateId()));
+            return Cli::RETURN_FAILURE;
+        }
+
+        $targetDir = $this->fallbackResolver->getThemeTargetDir($fallbackDirs, $theme);
+        if ($targetDir === null) {
+            $this->io->error(sprintf(
+                "Could not determine the override directory inside theme '%s'.",
+                $theme->getCode(),
+            ));
+            return Cli::RETURN_FAILURE;
+        }
+        $targetFile = $targetDir . '/' . $templatePath;
+
+        $sourceFile = $this->fallbackResolver->findFirstExistingFile($fallbackDirs, $templatePath);
+        if ($sourceFile === null) {
+            $this->io->error(sprintf(
+                'Template %s was not found in any fallback location.',
+                $reference->getTemplateId(),
+            ));
+            $this->displayFallbackDirs($fallbackDirs, null, $targetDir, $templatePath);
+            return Cli::RETURN_FAILURE;
+        }
+
+        $overrideExists = $sourceFile === $targetFile;
+        if ($overrideExists && !$isForce) {
+            $this->io->info(sprintf(
+                'The template is already overridden in this theme: %s',
+                $this->toRelativePath($targetFile),
+            ));
+            $this->io->text('Use --force to replace it with the next file in the fallback chain.');
+            return Cli::RETURN_SUCCESS;
+        }
+
+        if ($overrideExists) {
+            $sourceFile = $this->fallbackResolver->findFirstExistingFile($fallbackDirs, $templatePath, $targetDir);
+            if ($sourceFile === null) {
+                $this->io->error('No other file found in the fallback chain to copy the override from.');
+                return Cli::RETURN_FAILURE;
+            }
+        }
+
+        $this->io->newLine();
+        $this->io->definitionList(
+            ['Template' => $reference->getTemplateId()],
+            ['Theme' => $theme->getCode()],
+            ['Source' => $this->toRelativePath($sourceFile)],
+            ['Target' => $this->toRelativePath($targetFile)],
+        );
+
+        if ($isDryRun || $this->isVerbose($output)) {
+            $this->displayFallbackDirs($fallbackDirs, $sourceFile, $targetDir, $templatePath);
+        }
+
+        if ($isDryRun) {
+            $this->io->success('Dry run: no files were copied.');
+            return Cli::RETURN_SUCCESS;
+        }
+
+        if ($overrideExists) {
+            $this->io->text('Replacing the existing override (--force).');
+        }
+
+        $this->templateCopier->copy($sourceFile, $targetFile);
+
+        // Verify that Magento's fallback now resolves the template to the new override
+        $resolved = $this->fallbackResolver->findFirstExistingFile($fallbackDirs, $templatePath);
+        if ($resolved !== $targetFile) {
+            $this->io->warning(sprintf(
+                'The file was copied, but Magento resolves the template to %s instead of the new override.',
+                $resolved === null ? 'nothing' : $this->toRelativePath($resolved),
+            ));
+            return Cli::RETURN_FAILURE;
+        }
+
+        $this->cacheCleaner->clean($this->io, $this->isVerbose($output));
+
+        $this->io->success(sprintf('Template override created: %s', $this->toRelativePath($targetFile)));
+        return Cli::RETURN_SUCCESS;
+    }
+
+    /**
+     * Get the template input from the argument or an interactive prompt
+     *
+     * @param InputInterface $input
+     * @param OutputInterface $output
+     * @return string|null
+     */
+    private function resolveTemplateInput(InputInterface $input, OutputInterface $output): ?string
+    {
+        /** @var string|null $templateArg */
+        $templateArg = $input->getArgument('template');
+        if ($templateArg !== null && trim($templateArg) !== '') {
+            return trim($templateArg);
+        }
+
+        if (!$this->isInteractiveTerminal($output)) {
+            return null;
+        }
+
+        $this->setPromptEnvironment();
+        $prompt = new TextPrompt(
+            label: 'Which template do you want to override?',
+            placeholder: 'Magento_Catalog::product/view/details.phtml',
+            required: true,
+            hint: 'Module_Name::path/to/template.phtml notation or a file path',
+        );
+
+        try {
+            $value = $prompt->prompt();
+            \Laravel\Prompts\Prompt::terminal()->restoreTty();
+            $this->resetPromptEnvironment();
+            $value = is_string($value) ? trim($value) : '';
+
+            return $value === '' ? null : $value;
+        } catch (\Exception $e) {
+            $this->resetPromptEnvironment();
+            $this->io->error('Interactive mode failed: ' . $e->getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * Resolve the target theme from the option or an interactive prompt
+     *
+     * @param string|null $themeOption
+     * @param array<string,ThemeInterface> $frontendThemes
+     * @param OutputInterface $output
+     * @return ThemeInterface|null
+     */
+    private function resolveTheme(?string $themeOption, array $frontendThemes, OutputInterface $output): ?ThemeInterface
+    {
+        if ($themeOption !== null && $themeOption !== '') {
+            return $this->resolveThemeFromOption($themeOption, $frontendThemes, $output);
+        }
+
+        if (!$this->isInteractiveTerminal($output)) {
+            $this->displayAvailableThemes($frontendThemes);
+            return null;
+        }
+
+        return $this->promptForTheme($frontendThemes);
+    }
+
+    /**
+     * Resolve a theme given via the --theme option, offering suggestions when invalid
+     *
+     * @param string $themeCode
+     * @param array<string,ThemeInterface> $frontendThemes
+     * @param OutputInterface $output
+     * @return ThemeInterface|null
+     */
+    private function resolveThemeFromOption(
+        string $themeCode,
+        array $frontendThemes,
+        OutputInterface $output,
+    ): ?ThemeInterface {
+        if (isset($frontendThemes[$themeCode])) {
+            return $frontendThemes[$themeCode];
+        }
+
+        $correctedTheme = $this->handleInvalidThemeWithSuggestions($themeCode, $this->themeSuggester, $output);
+        if ($correctedTheme !== null && isset($frontendThemes[$correctedTheme])) {
+            $this->io->info("Using theme: $correctedTheme");
+            return $frontendThemes[$correctedTheme];
+        }
+
+        return null;
+    }
+
+    /**
+     * Let the user pick the target theme interactively
+     *
+     * @param array<string,ThemeInterface> $frontendThemes
+     * @return ThemeInterface|null
+     */
+    private function promptForTheme(array $frontendThemes): ?ThemeInterface
+    {
+        $options = array_keys($frontendThemes);
+
+        $this->setPromptEnvironment();
+        $prompt = new SearchPrompt(
+            label: 'Select the target theme',
+            options: static fn(string $value) => $value === ''
+                ? $options
+                : array_values(array_filter($options, static fn(string $option) => stripos($option, $value) !== false)),
+            placeholder: 'Type to search theme...',
+            scroll: 10,
+            hint: 'Type to search, arrow keys to navigate, Enter to confirm',
+        );
+
+        try {
+            $selection = $prompt->prompt();
+            \Laravel\Prompts\Prompt::terminal()->restoreTty();
+            $this->resetPromptEnvironment();
+
+            return is_string($selection) ? $frontendThemes[$selection] ?? null : null;
+        } catch (\Exception $e) {
+            $this->resetPromptEnvironment();
+            $this->io->error('Interactive mode failed: ' . $e->getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * Get all frontend themes keyed by theme code
+     *
+     * @return array<string,ThemeInterface>
+     */
+    private function getFrontendThemes(): array
+    {
+        $themes = [];
+        foreach ($this->themeList->getAllThemes() as $theme) {
+            if ($theme->getArea() !== Area::AREA_FRONTEND) {
+                continue;
+            }
+            $themes[$theme->getCode()] = $theme;
+        }
+
+        return $themes;
+    }
+
+    /**
+     * Display the fallback search order with source and target markers
+     *
+     * @param string[] $fallbackDirs
+     * @param string|null $sourceFile
+     * @param string $targetDir
+     * @param string $templatePath
+     * @return void
+     */
+    private function displayFallbackDirs(
+        array $fallbackDirs,
+        ?string $sourceFile,
+        string $targetDir,
+        string $templatePath,
+    ): void {
+        $this->io->text('Fallback search order (the first existing file wins):');
+
+        $rows = [];
+        $position = 0;
+        foreach ($fallbackDirs as $dir) {
+            $position++;
+            $notes = [];
+            if ($dir === $targetDir) {
+                $notes[] = 'override target';
+            }
+            if ($sourceFile !== null && $sourceFile === $dir . '/' . $templatePath) {
+                $notes[] = 'current source';
+            }
+            $rows[] = [$position, $this->toRelativePath($dir), implode(', ', $notes)];
+        }
+
+        $this->io->table(['#', 'Directory', ''], $rows);
+    }
+
+    /**
+     * Display available frontend themes with usage instructions
+     *
+     * @param array<string,ThemeInterface> $frontendThemes
+     * @return void
+     */
+    private function displayAvailableThemes(array $frontendThemes): void
+    {
+        $this->io->writeln('No theme specified. Available frontend themes:');
+        foreach (array_keys($frontendThemes) as $code) {
+            $this->io->writeln("  - $code");
+        }
+        $this->io->newLine();
+        $this->displayUsage();
+    }
+
+    /**
+     * Display usage examples
+     *
+     * @return void
+     */
+    private function displayUsage(): void
+    {
+        $this->io->writeln('Usage: bin/magento mageforge:template:override <template> --theme <theme-code>');
+        $this->io->writeln(
+            'Example: bin/magento mageforge:template:override '
+            . "'Magento_Catalog::product/view/details.phtml' --theme Vendor/theme",
+        );
+        $this->io->writeln('The template can also be given as a file path, e.g.');
+        $this->io->writeln('  vendor/magento/module-catalog/view/frontend/templates/product/view/details.phtml');
+    }
+
+    /**
+     * Make a path relative to the Magento root directory for display
+     *
+     * @param string $path
+     * @return string
+     */
+    private function toRelativePath(string $path): string
+    {
+        $root = rtrim(str_replace('\\', '/', $this->directoryList->getRoot()), '/');
+        $normalized = str_replace('\\', '/', $path);
+        if ($root !== '' && str_starts_with($normalized, $root . '/')) {
+            return substr($normalized, strlen($root) + 1);
+        }
+
+        return $path;
+    }
+}
diff --git a/src/Model/TemplateReference.php b/src/Model/TemplateReference.php
new file mode 100644
index 00000000..8032c378
--- /dev/null
+++ b/src/Model/TemplateReference.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Model;
+
+/**
+ * Value object describing a module template, e.g. "Magento_Catalog::product/view/details.phtml"
+ */
+class TemplateReference
+{
+    /**
+     * @param string $moduleName Module name in Vendor_Module notation
+     * @param string $templatePath Path relative to the module's templates directory
+     */
+    public function __construct(
+        private readonly string $moduleName,
+        private readonly string $templatePath,
+    ) {
+    }
+
+    /**
+     * Get the module name in Vendor_Module notation
+     *
+     * @return string
+     */
+    public function getModuleName(): string
+    {
+        return $this->moduleName;
+    }
+
+    /**
+     * Get the template path relative to the templates directory
+     *
+     * @return string
+     */
+    public function getTemplatePath(): string
+    {
+        return $this->templatePath;
+    }
+
+    /**
+     * Get the full template identifier in Module_Name::path/to/template.phtml notation
+     *
+     * @return string
+     */
+    public function getTemplateId(): string
+    {
+        return $this->moduleName . '::' . $this->templatePath;
+    }
+}
diff --git a/src/Service/TemplateOverride/AreaEmulator.php b/src/Service/TemplateOverride/AreaEmulator.php
new file mode 100644
index 00000000..89a6a976
--- /dev/null
+++ b/src/Service/TemplateOverride/AreaEmulator.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service\TemplateOverride;
+
+use Magento\Framework\App\State;
+use Magento\Framework\Exception\LocalizedException;
+use Magento\Framework\ObjectManager\ConfigLoaderInterface;
+use Magento\Framework\ObjectManagerInterface;
+
+/**
+ * Loads the dependency injection configuration of a given area into the CLI object manager
+ *
+ * CLI commands run without any area specific DI configuration. View file fallback plugins
+ * (for example Hyvä's compat module fallback, registered in etc/frontend/di.xml) only take
+ * effect after the area's DI configuration has been loaded.
+ */
+class AreaEmulator
+{
+    /**
+     * @param State $appState
+     * @param ConfigLoaderInterface $configLoader
+     * @param ObjectManagerInterface $objectManager
+     */
+    public function __construct(
+        private readonly State $appState,
+        private readonly ConfigLoaderInterface $configLoader,
+        private readonly ObjectManagerInterface $objectManager,
+    ) {
+    }
+
+    /**
+     * Set the area code (if not set yet) and load the area's DI configuration
+     *
+     * @param string $areaCode
+     * @return void
+     */
+    public function emulate(string $areaCode): void
+    {
+        try {
+            $currentArea = $this->appState->getAreaCode();
+        } catch (LocalizedException) {
+            $currentArea = null;
+        }
+
+        if ($currentArea === null) {
+            $this->appState->setAreaCode($areaCode);
+        }
+
+        $this->objectManager->configure($this->configLoader->load($areaCode));
+    }
+}
diff --git a/src/Service/TemplateOverride/CompatModuleResolver.php b/src/Service/TemplateOverride/CompatModuleResolver.php
new file mode 100644
index 00000000..1c5010d9
--- /dev/null
+++ b/src/Service/TemplateOverride/CompatModuleResolver.php
@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service\TemplateOverride;
+
+use Magento\Framework\ObjectManagerInterface;
+
+/**
+ * Maps Hyvä compatibility modules to the original modules they provide templates for
+ *
+ * Hyvä compat modules register themselves in Hyvä's CompatModuleRegistry (frontend area DI).
+ * Because Hyvä is an optional dependency, its registry class is looked up dynamically and an
+ * empty result is returned when it is not installed. The frontend area DI configuration must
+ * be loaded before using this service (see AreaEmulator), otherwise the registry is empty.
+ */
+class CompatModuleResolver
+{
+    // phpcs:ignore Magento2.PHP.LiteralNamespaces.LiteralClassUsage -- Hyvä is an optional dependency
+    private const HYVA_COMPAT_REGISTRY = 'Hyva\CompatModuleFallback\Model\CompatModuleRegistry';
+
+    /**
+     * @param ObjectManagerInterface $objectManager
+     * @param string|null $registryClassName Overridable for testing; defaults to Hyvä's registry
+     */
+    public function __construct(
+        private readonly ObjectManagerInterface $objectManager,
+        private readonly ?string $registryClassName = null,
+    ) {
+    }
+
+    /**
+     * Get the original module(s) a Hyvä compatibility module provides templates for
+     *
+     * Returns an empty array if Hyvä's compat module fallback is not installed or the given
+     * module is not registered as a compatibility module.
+     *
+     * @param string $moduleName
+     * @return array<int, string>
+     */
+    public function getOriginalModules(string $moduleName): array
+    {
+        $map = $this->getCompatToOriginalMap();
+
+        return $map[$moduleName] ?? [];
+    }
+
+    /**
+     * Build the map of compat module => original modules from Hyvä's registry
+     *
+     * @return array<string, array<int, string>>
+     */
+    private function getCompatToOriginalMap(): array
+    {
+        $registryClass = $this->registryClassName ?? self::HYVA_COMPAT_REGISTRY;
+        if (!class_exists($registryClass)) {
+            return [];
+        }
+
+        $registry = $this->objectManager->create($registryClass);
+        if (!is_object($registry)) {
+            return [];
+        }
+        if (!method_exists($registry, 'getOrigModules') || !method_exists($registry, 'getCompatModulesFor')) {
+            return [];
+        }
+
+        $originalModules = $registry->getOrigModules();
+        if (!is_array($originalModules)) {
+            return [];
+        }
+
+        $map = [];
+        foreach ($originalModules as $originalModule) {
+            if (!is_string($originalModule)) {
+                continue;
+            }
+            $compatModules = $registry->getCompatModulesFor($originalModule);
+            if (!is_array($compatModules)) {
+                continue;
+            }
+            foreach ($compatModules as $compatModule) {
+                if (is_string($compatModule)) {
+                    $map[$compatModule][] = $originalModule;
+                }
+            }
+        }
+
+        return $map;
+    }
+}
diff --git a/src/Service/TemplateOverride/TemplateCopier.php b/src/Service/TemplateOverride/TemplateCopier.php
new file mode 100644
index 00000000..47894ef8
--- /dev/null
+++ b/src/Service/TemplateOverride/TemplateCopier.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service\TemplateOverride;
+
+use Magento\Framework\Filesystem\Driver\File;
+
+/**
+ * Copies a template file to its override location, creating directories as needed
+ */
+class TemplateCopier
+{
+    /**
+     * @param File $fileDriver
+     */
+    public function __construct(
+        private readonly File $fileDriver,
+    ) {
+    }
+
+    /**
+     * Copy the source template to the target location
+     *
+     * @param string $sourceFile
+     * @param string $targetFile
+     * @return void
+     * @throws \Magento\Framework\Exception\FileSystemException
+     */
+    public function copy(string $sourceFile, string $targetFile): void
+    {
+        $targetDir = $this->fileDriver->getParentDirectory($targetFile);
+        if (!$this->fileDriver->isDirectory($targetDir)) {
+            $this->fileDriver->createDirectory($targetDir);
+        }
+
+        $this->fileDriver->copy($sourceFile, $targetFile);
+    }
+}
diff --git a/src/Service/TemplateOverride/TemplateFallbackResolver.php b/src/Service/TemplateOverride/TemplateFallbackResolver.php
new file mode 100644
index 00000000..16aa4a1c
--- /dev/null
+++ b/src/Service/TemplateOverride/TemplateFallbackResolver.php
@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service\TemplateOverride;
+
+use Magento\Framework\Component\ComponentRegistrar;
+use Magento\Framework\Component\ComponentRegistrarInterface;
+use Magento\Framework\Filesystem\Driver\File;
+use Magento\Framework\ObjectManagerInterface;
+use Magento\Framework\View\Design\Fallback\RulePool;
+use Magento\Framework\View\Design\ThemeInterface;
+use Magento\Framework\View\DesignInterface;
+use OpenForgeProject\MageForge\Model\TemplateReference;
+
+/**
+ * Determines template fallback directories exactly as Magento does at runtime
+ *
+ * Uses Magento's own template fallback rule (RulePool), so any installed plugins - such as
+ * Hyvä's compat module fallback - are taken into account. The target area's DI configuration
+ * must be loaded first (see AreaEmulator) for such plugins to be active.
+ */
+class TemplateFallbackResolver
+{
+    /**
+     * @param ObjectManagerInterface $objectManager
+     * @param DesignInterface $design
+     * @param ComponentRegistrarInterface $componentRegistrar
+     * @param File $fileDriver
+     */
+    public function __construct(
+        private readonly ObjectManagerInterface $objectManager,
+        private readonly DesignInterface $design,
+        private readonly ComponentRegistrarInterface $componentRegistrar,
+        private readonly File $fileDriver,
+    ) {
+    }
+
+    /**
+     * Get the ordered list of directories Magento searches for the given template
+     *
+     * @param TemplateReference $reference
+     * @param ThemeInterface $theme
+     * @return string[]
+     */
+    public function getFallbackDirs(TemplateReference $reference, ThemeInterface $theme): array
+    {
+        $area = $theme->getArea();
+        // Fallback plugins like Hyvä's compat module fallback check the "current" design theme
+        $this->design->setDesignTheme($theme, $area);
+
+        // A fresh RulePool instance is created so that fallback rule plugins registered in the
+        // area's DI configuration (loaded after the CLI booted) are applied.
+        $rulePool = $this->objectManager->create(RulePool::class);
+        if (!$rulePool instanceof RulePool) {
+            throw new \RuntimeException('Could not create the view fallback rule pool.');
+        }
+
+        $dirs = $rulePool
+            ->getRule(RulePool::TYPE_TEMPLATE_FILE)
+            ->getPatternDirs([
+                'area' => $area,
+                'theme' => $theme,
+                'module_name' => $reference->getModuleName(),
+                'file' => $reference->getTemplatePath(),
+            ]);
+
+        $result = [];
+        foreach ($dirs as $dir) {
+            if (is_string($dir) && !in_array($dir, $result, true)) {
+                $result[] = $dir;
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Find the first existing file for the template within the fallback directories
+     *
+     * This mirrors how Magento resolves a template: the first directory in the fallback order
+     * containing the file wins. An optional directory can be excluded from the search to find
+     * the file that would be used if the excluded location did not exist.
+     *
+     * @param string[] $fallbackDirs
+     * @param string $templatePath
+     * @param string|null $excludedDir
+     * @return string|null
+     */
+    public function findFirstExistingFile(
+        array $fallbackDirs,
+        string $templatePath,
+        ?string $excludedDir = null,
+    ): ?string {
+        foreach ($fallbackDirs as $dir) {
+            if ($dir === $excludedDir) {
+                continue;
+            }
+            $file = $dir . '/' . $templatePath;
+            if ($this->fileDriver->isFile($file)) {
+                return $file;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the fallback directory located within the given theme itself (the override target)
+     *
+     * @param string[] $fallbackDirs
+     * @param ThemeInterface $theme
+     * @return string|null
+     */
+    public function getThemeTargetDir(array $fallbackDirs, ThemeInterface $theme): ?string
+    {
+        $themePath = $this->componentRegistrar->getPath(ComponentRegistrar::THEME, $theme->getFullPath());
+        if ($themePath === null) {
+            return null;
+        }
+
+        $themePath = rtrim(str_replace('\\', '/', $themePath), '/');
+        foreach ($fallbackDirs as $dir) {
+            $normalizedDir = str_replace('\\', '/', $dir);
+            if ($normalizedDir === $themePath || str_starts_with($normalizedDir, $themePath . '/')) {
+                return $dir;
+            }
+        }
+
+        return null;
+    }
+}
diff --git a/src/Service/TemplateOverride/TemplatePathParser.php b/src/Service/TemplateOverride/TemplatePathParser.php
new file mode 100644
index 00000000..816d1502
--- /dev/null
+++ b/src/Service/TemplateOverride/TemplatePathParser.php
@@ -0,0 +1,289 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service\TemplateOverride;
+
+use Magento\Framework\App\Filesystem\DirectoryList;
+use Magento\Framework\Component\ComponentRegistrar;
+use Magento\Framework\Component\ComponentRegistrarInterface;
+use Magento\Framework\Filesystem\Driver\File;
+use OpenForgeProject\MageForge\Model\TemplateReference;
+
+/**
+ * Parses user input into a template reference
+ *
+ * Accepts the Module_Name::path/to/template.phtml notation as well as filesystem paths into
+ * a module's view/<area>/templates directory or a theme's <Module_Name>/templates directory.
+ * Hyvä compatibility module references are normalized to the original module, because theme
+ * overrides always use the original module's name as directory name.
+ */
+class TemplatePathParser
+{
+    /**
+     * @param ComponentRegistrarInterface $componentRegistrar
+     * @param CompatModuleResolver $compatModuleResolver
+     * @param File $fileDriver
+     * @param DirectoryList $directoryList
+     */
+    public function __construct(
+        private readonly ComponentRegistrarInterface $componentRegistrar,
+        private readonly CompatModuleResolver $compatModuleResolver,
+        private readonly File $fileDriver,
+        private readonly DirectoryList $directoryList,
+    ) {
+    }
+
+    /**
+     * Parse a template reference or file path into a TemplateReference
+     *
+     * @param string $input
+     * @return TemplateReference
+     * @throws \InvalidArgumentException
+     */
+    public function parse(string $input): TemplateReference
+    {
+        $input = trim($input);
+        if ($input === '') {
+            throw new \InvalidArgumentException('Template reference must not be empty.');
+        }
+
+        if (str_contains($input, '::')) {
+            return $this->parseTemplateId($input);
+        }
+
+        return $this->parseFilePath($input);
+    }
+
+    /**
+     * Parse the Module_Name::path/to/template.phtml notation
+     *
+     * @param string $input
+     * @return TemplateReference
+     * @throws \InvalidArgumentException
+     */
+    private function parseTemplateId(string $input): TemplateReference
+    {
+        [$moduleName, $templatePath] = explode('::', $input, 2);
+        $moduleName = trim($moduleName);
+        $templatePath = $this->normalizeTemplatePath($templatePath);
+
+        if ($moduleName === '' || $templatePath === '') {
+            throw new \InvalidArgumentException(
+                "Invalid template reference '$input'. Expected format: Module_Name::path/to/template.phtml",
+            );
+        }
+
+        if ($this->componentRegistrar->getPath(ComponentRegistrar::MODULE, $moduleName) === null) {
+            throw new \InvalidArgumentException("Module '$moduleName' is not registered in this installation.");
+        }
+
+        return $this->createReference($moduleName, $templatePath);
+    }
+
+    /**
+     * Parse a filesystem path pointing into a module or theme templates directory
+     *
+     * @param string $input
+     * @return TemplateReference
+     * @throws \InvalidArgumentException
+     */
+    private function parseFilePath(string $input): TemplateReference
+    {
+        $absolutePath = $this->locateFile(str_replace('\\', '/', $input));
+        if ($absolutePath === null) {
+            throw new \InvalidArgumentException(
+                "Template file '$input' not found. Pass an existing file path or use the "
+                . 'Module_Name::path/to/template.phtml notation.',
+            );
+        }
+
+        $moduleReference = $this->matchModuleFile($absolutePath);
+        if ($moduleReference !== null) {
+            return $moduleReference;
+        }
+
+        $themeReference = $this->matchThemeFile($absolutePath);
+        if ($themeReference !== null) {
+            return $themeReference;
+        }
+
+        throw new \InvalidArgumentException(
+            "The file '$input' does not belong to a registered module or theme view directory.",
+        );
+    }
+
+    /**
+     * Locate a file by its path, trying the working directory and the Magento root
+     *
+     * Relative paths are first resolved against the current working directory and then
+     * against the Magento root, so paths like vendor/module/... work from any directory.
+     *
+     * @param string $path
+     * @return string|null The normalized absolute path, or null when the file does not exist
+     */
+    private function locateFile(string $path): ?string
+    {
+        $candidates = [$path];
+        if (!str_starts_with($path, '/')) {
+            $root = rtrim(str_replace('\\', '/', $this->directoryList->getRoot()), '/');
+            if ($root !== '') {
+                $candidates[] = $root . '/' . $path;
+            }
+        }
+
+        foreach ($candidates as $candidate) {
+            if (!$this->fileDriver->isFile($candidate)) {
+                continue;
+            }
+            $realPath = $this->fileDriver->getRealPath($candidate);
+            if (is_string($realPath)) {
+                return str_replace('\\', '/', $realPath);
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Match a file inside a module's view/<area>/templates directory
+     *
+     * @param string $absolutePath
+     * @return TemplateReference|null
+     * @throws \InvalidArgumentException
+     */
+    private function matchModuleFile(string $absolutePath): ?TemplateReference
+    {
+        $match = $this->findOwningComponent($absolutePath, ComponentRegistrar::MODULE);
+        if ($match === null) {
+            return null;
+        }
+
+        [$moduleName, $relativePath] = $match;
+        $matches = [];
+        if (!preg_match('#^view/[a-z_]+/templates/(.+)$#', $relativePath, $matches)) {
+            throw new \InvalidArgumentException(sprintf(
+                "The file belongs to module '%s' but is not inside a view/<area>/templates directory.",
+                $moduleName,
+            ));
+        }
+
+        return $this->createReference($moduleName, $matches[1]);
+    }
+
+    /**
+     * Match a file inside a theme's <Module_Name>/templates directory
+     *
+     * @param string $absolutePath
+     * @return TemplateReference|null
+     * @throws \InvalidArgumentException
+     */
+    private function matchThemeFile(string $absolutePath): ?TemplateReference
+    {
+        $match = $this->findOwningComponent($absolutePath, ComponentRegistrar::THEME);
+        if ($match === null) {
+            return null;
+        }
+
+        [$themeFullPath, $relativePath] = $match;
+        $matches = [];
+        if (!preg_match('#^([A-Za-z0-9]+_[A-Za-z0-9]+)/templates/(.+)$#', $relativePath, $matches)) {
+            throw new \InvalidArgumentException(sprintf(
+                "The file belongs to theme '%s' but is not a module template override "
+                . '(expected <Module_Name>/templates/...).',
+                $themeFullPath,
+            ));
+        }
+
+        return $this->createReference($matches[1], $matches[2]);
+    }
+
+    /**
+     * Find the registered component (longest path match) containing the given file
+     *
+     * @param string $absolutePath
+     * @param string $componentType
+     * @return array{0: string, 1: string}|null Component name and file path relative to the component root
+     */
+    private function findOwningComponent(string $absolutePath, string $componentType): ?array
+    {
+        $bestName = null;
+        $bestPath = '';
+
+        foreach ($this->componentRegistrar->getPaths($componentType) as $name => $componentPath) {
+            if (!is_string($componentPath)) {
+                continue;
+            }
+            $componentPath = rtrim(str_replace('\\', '/', $componentPath), '/');
+            if ($componentPath === '' || !str_starts_with($absolutePath, $componentPath . '/')) {
+                continue;
+            }
+            if (strlen($componentPath) > strlen($bestPath)) {
+                $bestName = (string) $name;
+                $bestPath = $componentPath;
+            }
+        }
+
+        if ($bestName === null) {
+            return null;
+        }
+
+        return [$bestName, substr($absolutePath, strlen($bestPath) + 1)];
+    }
+
+    /**
+     * Create the reference, normalizing Hyvä compat modules to their original module
+     *
+     * Theme overrides always live in a directory named after the original module, even when
+     * the template currently in effect is shipped by a Hyvä compatibility module.
+     *
+     * @param string $moduleName
+     * @param string $templatePath
+     * @return TemplateReference
+     * @throws \InvalidArgumentException
+     */
+    private function createReference(string $moduleName, string $templatePath): TemplateReference
+    {
+        $originalModules = $this->compatModuleResolver->getOriginalModules($moduleName);
+        if ($originalModules === []) {
+            return new TemplateReference($moduleName, $templatePath);
+        }
+
+        // Compat modules may keep templates in a subdirectory named after the original module
+        foreach ($originalModules as $originalModule) {
+            if (str_starts_with($templatePath, $originalModule . '/')) {
+                return new TemplateReference($originalModule, substr($templatePath, strlen($originalModule) + 1));
+            }
+        }
+
+        if (count($originalModules) === 1) {
+            return new TemplateReference($originalModules[0], $templatePath);
+        }
+
+        throw new \InvalidArgumentException(sprintf(
+            "'%s' is a Hyvä compatibility module for several modules (%s). "
+            . "Please reference the template by its original module, e.g. '%s::%s'.",
+            $moduleName,
+            implode(', ', $originalModules),
+            $originalModules[0],
+            $templatePath,
+        ));
+    }
+
+    /**
+     * Normalize a template path and reject relative path segments
+     *
+     * @param string $path
+     * @return string
+     * @throws \InvalidArgumentException
+     */
+    private function normalizeTemplatePath(string $path): string
+    {
+        $normalized = ltrim(trim(str_replace('\\', '/', $path)), '/');
+        if (str_contains($normalized, './')) {
+            throw new \InvalidArgumentException("Template path '$path' must not contain relative path segments.");
+        }
+
+        return $normalized;
+    }
+}
diff --git a/src/etc/di.xml b/src/etc/di.xml
index 2fe48a73..dd40f106 100644
--- a/src/etc/di.xml
+++ b/src/etc/di.xml
@@ -25,6 +25,8 @@
                               OpenForgeProject\MageForge\Console\Command\Theme\TokensCommand</item>
                         <item name="mageforge_dev_inspector" xsi:type="object">
                               OpenForgeProject\MageForge\Console\Command\Dev\InspectorCommand</item>
+                        <item name="mageforge_template_override" xsi:type="object">
+                              OpenForgeProject\MageForge\Console\Command\Template\OverrideCommand</item>
                   </argument>
             </arguments>
       </type>
diff --git a/tests/Unit/Console/Command/Template/OverrideCommandTest.php b/tests/Unit/Console/Command/Template/OverrideCommandTest.php
new file mode 100644
index 00000000..d6ee5350
--- /dev/null
+++ b/tests/Unit/Console/Command/Template/OverrideCommandTest.php
@@ -0,0 +1,317 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Console\Command\Template;
+
+use Magento\Framework\App\Filesystem\DirectoryList;
+use Magento\Framework\Console\Cli;
+use OpenForgeProject\MageForge\Console\Command\Template\OverrideCommand;
+use OpenForgeProject\MageForge\Model\TemplateReference;
+use OpenForgeProject\MageForge\Model\ThemeList;
+use OpenForgeProject\MageForge\Service\CacheCleaner;
+use OpenForgeProject\MageForge\Service\TemplateOverride\AreaEmulator;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateCopier;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateFallbackResolver;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplatePathParser;
+use OpenForgeProject\MageForge\Service\ThemeSuggester;
+use OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride\FakeTheme;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Console\Tester\CommandTester;
+
+class OverrideCommandTest extends TestCase
+{
+    private const THEME_DIR = '/magento/app/design/frontend/Vendor/theme/Magento_Catalog/templates';
+    private const MODULE_DIR = '/magento/vendor/magento/module-catalog/view/frontend/templates';
+
+    private ThemeList&MockObject $themeList;
+    private ThemeSuggester&MockObject $themeSuggester;
+    private TemplatePathParser&MockObject $templatePathParser;
+    private TemplateFallbackResolver&MockObject $fallbackResolver;
+    private TemplateCopier&MockObject $templateCopier;
+    private AreaEmulator&MockObject $areaEmulator;
+    private CacheCleaner&MockObject $cacheCleaner;
+    private DirectoryList&MockObject $directoryList;
+    private OverrideCommand $command;
+
+    protected function setUp(): void
+    {
+        $this->themeList = $this->createMock(ThemeList::class);
+        $this->themeSuggester = $this->createMock(ThemeSuggester::class);
+        $this->templatePathParser = $this->createMock(TemplatePathParser::class);
+        $this->fallbackResolver = $this->createMock(TemplateFallbackResolver::class);
+        $this->templateCopier = $this->createMock(TemplateCopier::class);
+        $this->areaEmulator = $this->createMock(AreaEmulator::class);
+        $this->cacheCleaner = $this->createMock(CacheCleaner::class);
+        $this->directoryList = $this->createMock(DirectoryList::class);
+        $this->directoryList->method('getRoot')->willReturn('/magento');
+        $this->command = new OverrideCommand(
+            $this->themeList,
+            $this->themeSuggester,
+            $this->templatePathParser,
+            $this->fallbackResolver,
+            $this->templateCopier,
+            $this->areaEmulator,
+            $this->cacheCleaner,
+            $this->directoryList,
+        );
+    }
+
+    public function testCommandNameAndAlias(): void
+    {
+        $this->assertSame('mageforge:template:override', $this->command->getName());
+        $this->assertSame(['template:override'], $this->command->getAliases());
+    }
+
+    public function testWarnsWhenNoFrontendThemesExist(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([]);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $this->assertStringContainsString('No frontend themes found.', $tester->getDisplay());
+    }
+
+    public function testMissingTemplateArgumentShowsUsageInNonInteractiveMode(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([new FakeTheme('Vendor/theme')]);
+        $this->templatePathParser->expects($this->never())->method('parse');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('Usage: bin/magento mageforge:template:override', $display);
+        $this->assertStringContainsString('Magento_Catalog::product/view/details.phtml', $display);
+    }
+
+    public function testMissingThemeOptionListsThemesInNonInteractiveMode(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([
+            new FakeTheme('Vendor/theme'),
+            new FakeTheme('Vendor/other'),
+        ]);
+        $this->areaEmulator->expects($this->never())->method('emulate');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute(['template' => 'Magento_Catalog::product/view/details.phtml']);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('No theme specified. Available frontend themes:', $display);
+        $this->assertStringContainsString('Vendor/theme', $display);
+        $this->assertStringContainsString('Vendor/other', $display);
+    }
+
+    public function testUnknownThemeWithoutSuggestionsFails(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([new FakeTheme('Vendor/theme')]);
+        $this->themeSuggester->method('findSimilarThemes')->willReturn([]);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/unknown',
+        ]);
+
+        $this->assertSame(Cli::RETURN_FAILURE, $exitCode);
+        $this->assertStringContainsString("Theme 'Vendor/unknown' is not installed", $tester->getDisplay());
+    }
+
+    public function testAdminhtmlThemesAreNotOfferedAsTargets(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([
+            new FakeTheme('Magento/backend', 'adminhtml'),
+        ]);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $this->assertStringContainsString('No frontend themes found.', $tester->getDisplay());
+    }
+
+    public function testCopiesTemplateAndCleansCache(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturnOnConsecutiveCalls(
+                self::MODULE_DIR . '/product/view/details.phtml',
+                self::THEME_DIR . '/product/view/details.phtml',
+            );
+        $this->templateCopier
+            ->expects($this->once())
+            ->method('copy')
+            ->with(
+                self::MODULE_DIR . '/product/view/details.phtml',
+                self::THEME_DIR . '/product/view/details.phtml',
+            );
+        $this->areaEmulator->expects($this->once())->method('emulate')->with('frontend');
+        $this->cacheCleaner->expects($this->once())->method('clean')->willReturn(true);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('Magento_Catalog::product/view/details.phtml', $display);
+        $this->assertStringContainsString(
+            'app/design/frontend/Vendor/theme/Magento_Catalog/templates/product/view/details.phtml',
+            $display,
+        );
+        $this->assertStringContainsString('Template override created:', $display);
+    }
+
+    public function testDryRunShowsFallbackOrderWithoutCopying(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturn(self::MODULE_DIR . '/product/view/details.phtml');
+        $this->templateCopier->expects($this->never())->method('copy');
+        $this->cacheCleaner->expects($this->never())->method('clean');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+            '--dry-run' => true,
+        ]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('Fallback search order', $display);
+        $this->assertStringContainsString('override target', $display);
+        $this->assertStringContainsString('current source', $display);
+        $this->assertStringContainsString('Dry run: no files were copied.', $display);
+    }
+
+    public function testExistingOverrideIsNotReplacedWithoutForce(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturn(self::THEME_DIR . '/product/view/details.phtml');
+        $this->templateCopier->expects($this->never())->method('copy');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('already overridden in this theme', $display);
+        $this->assertStringContainsString('Use --force', $display);
+    }
+
+    public function testForceReplacesExistingOverrideFromNextFallbackSource(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturnOnConsecutiveCalls(
+                self::THEME_DIR . '/product/view/details.phtml',
+                self::MODULE_DIR . '/product/view/details.phtml',
+                self::THEME_DIR . '/product/view/details.phtml',
+            );
+        $this->templateCopier
+            ->expects($this->once())
+            ->method('copy')
+            ->with(
+                self::MODULE_DIR . '/product/view/details.phtml',
+                self::THEME_DIR . '/product/view/details.phtml',
+            );
+        $this->cacheCleaner->expects($this->once())->method('clean')->willReturn(true);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+            '--force' => true,
+        ]);
+
+        $this->assertSame(Cli::RETURN_SUCCESS, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('Replacing the existing override (--force).', $display);
+        $this->assertStringContainsString('Template override created:', $display);
+    }
+
+    public function testFailsWhenTemplateIsNotFoundInAnyFallbackLocation(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver->method('findFirstExistingFile')->willReturn(null);
+        $this->templateCopier->expects($this->never())->method('copy');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_FAILURE, $exitCode);
+        $display = $tester->getDisplay();
+        $this->assertStringContainsString('was not found in any fallback location', $display);
+        $this->assertStringContainsString('Fallback search order', $display);
+    }
+
+    public function testWarnsWhenVerificationDoesNotResolveToNewOverride(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturn(self::MODULE_DIR . '/product/view/details.phtml');
+        $this->templateCopier->expects($this->once())->method('copy');
+        $this->cacheCleaner->expects($this->never())->method('clean');
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_FAILURE, $exitCode);
+        $this->assertStringContainsString('Magento resolves the template to', $tester->getDisplay());
+    }
+
+    public function testReportsParserErrors(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([new FakeTheme('Vendor/theme')]);
+        $this->templatePathParser
+            ->method('parse')
+            ->willThrowException(new \InvalidArgumentException("Module 'Unknown_Module' is not registered."));
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Unknown_Module::some/template.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_FAILURE, $exitCode);
+        $this->assertStringContainsString("Module 'Unknown_Module' is not registered.", $tester->getDisplay());
+    }
+
+    /**
+     * Configure mocks for a template that resolves to the fake theme and module directories
+     */
+    private function setUpResolvableTemplate(): void
+    {
+        $this->themeList->method('getAllThemes')->willReturn([new FakeTheme('Vendor/theme')]);
+        $this->templatePathParser
+            ->method('parse')
+            ->willReturn(new TemplateReference('Magento_Catalog', 'product/view/details.phtml'));
+        $this->fallbackResolver
+            ->method('getFallbackDirs')
+            ->willReturn([self::THEME_DIR, self::MODULE_DIR]);
+        $this->fallbackResolver->method('getThemeTargetDir')->willReturn(self::THEME_DIR);
+    }
+}
diff --git a/tests/Unit/Model/TemplateReferenceTest.php b/tests/Unit/Model/TemplateReferenceTest.php
new file mode 100644
index 00000000..5692f6f0
--- /dev/null
+++ b/tests/Unit/Model/TemplateReferenceTest.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Model;
+
+use OpenForgeProject\MageForge\Model\TemplateReference;
+use PHPUnit\Framework\TestCase;
+
+class TemplateReferenceTest extends TestCase
+{
+    public function testExposesModuleNameAndTemplatePath(): void
+    {
+        $reference = new TemplateReference('Magento_Catalog', 'product/view/details.phtml');
+
+        $this->assertSame('Magento_Catalog', $reference->getModuleName());
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
+    public function testBuildsTemplateIdInModuleNotation(): void
+    {
+        $reference = new TemplateReference('Magento_Checkout', 'cart/item/default.phtml');
+
+        $this->assertSame('Magento_Checkout::cart/item/default.phtml', $reference->getTemplateId());
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/AreaEmulatorTest.php b/tests/Unit/Service/TemplateOverride/AreaEmulatorTest.php
new file mode 100644
index 00000000..208b15e2
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/AreaEmulatorTest.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\App\State;
+use Magento\Framework\Exception\LocalizedException;
+use Magento\Framework\ObjectManager\ConfigLoaderInterface;
+use Magento\Framework\ObjectManagerInterface;
+use OpenForgeProject\MageForge\Service\TemplateOverride\AreaEmulator;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class AreaEmulatorTest extends TestCase
+{
+    private State&MockObject $appState;
+    private ConfigLoaderInterface&MockObject $configLoader;
+    private ObjectManagerInterface&MockObject $objectManager;
+    private AreaEmulator $areaEmulator;
+
+    protected function setUp(): void
+    {
+        $this->appState = $this->createMock(State::class);
+        $this->configLoader = $this->createMock(ConfigLoaderInterface::class);
+        $this->objectManager = $this->createMock(ObjectManagerInterface::class);
+        $this->areaEmulator = new AreaEmulator($this->appState, $this->configLoader, $this->objectManager);
+    }
+
+    public function testSetsAreaCodeAndLoadsDiConfiguration(): void
+    {
+        $diConfig = ['preferences' => ['SomeInterface' => 'SomeClass']];
+        $this->appState
+            ->method('getAreaCode')
+            ->willThrowException(new LocalizedException(__('Area code is not set')));
+        $this->appState->expects($this->once())->method('setAreaCode')->with('frontend');
+        $this->configLoader->expects($this->once())->method('load')->with('frontend')->willReturn($diConfig);
+        $this->objectManager->expects($this->once())->method('configure')->with($diConfig);
+
+        $this->areaEmulator->emulate('frontend');
+    }
+
+    public function testLoadsDiConfigurationEvenWhenAreaCodeIsAlreadySet(): void
+    {
+        $this->appState->method('getAreaCode')->willReturn('adminhtml');
+        $this->appState->expects($this->never())->method('setAreaCode');
+        $this->configLoader->method('load')->with('frontend')->willReturn([]);
+        $this->objectManager->expects($this->once())->method('configure')->with([]);
+
+        $this->areaEmulator->emulate('frontend');
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/CompatModuleResolverTest.php b/tests/Unit/Service/TemplateOverride/CompatModuleResolverTest.php
new file mode 100644
index 00000000..33b40609
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/CompatModuleResolverTest.php
@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\ObjectManagerInterface;
+use OpenForgeProject\MageForge\Service\TemplateOverride\CompatModuleResolver;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class CompatModuleResolverTest extends TestCase
+{
+    private ObjectManagerInterface&MockObject $objectManager;
+
+    protected function setUp(): void
+    {
+        $this->objectManager = $this->createMock(ObjectManagerInterface::class);
+    }
+
+    public function testReturnsEmptyArrayWhenHyvaIsNotInstalled(): void
+    {
+        $this->objectManager->expects($this->never())->method('create');
+        $resolver = new CompatModuleResolver($this->objectManager);
+
+        $this->assertSame([], $resolver->getOriginalModules('Hyva_MagentoCatalogCompat'));
+    }
+
+    public function testReturnsEmptyArrayWhenRegistryClassDoesNotExist(): void
+    {
+        $this->objectManager->expects($this->never())->method('create');
+        $resolver = new CompatModuleResolver($this->objectManager, 'NonExistent\\Registry\\ClassName');
+
+        $this->assertSame([], $resolver->getOriginalModules('Some_Module'));
+    }
+
+    public function testMapsCompatModuleToOriginalModules(): void
+    {
+        $registry = new FakeCompatModuleRegistry([
+            'Amasty_Label' => ['Hyva_AmastyLabelCompat'],
+            'Magento_Catalog' => ['Hyva_MagentoCatalogCompat'],
+        ]);
+        $this->objectManager
+            ->method('create')
+            ->with(FakeCompatModuleRegistry::class)
+            ->willReturn($registry);
+        $resolver = new CompatModuleResolver($this->objectManager, FakeCompatModuleRegistry::class);
+
+        $this->assertSame(['Amasty_Label'], $resolver->getOriginalModules('Hyva_AmastyLabelCompat'));
+        $this->assertSame(['Magento_Catalog'], $resolver->getOriginalModules('Hyva_MagentoCatalogCompat'));
+    }
+
+    public function testReturnsAllOriginalModulesForSharedCompatModule(): void
+    {
+        $registry = new FakeCompatModuleRegistry([
+            'Vendor_ModuleA' => ['Hyva_SharedCompat'],
+            'Vendor_ModuleB' => ['Hyva_SharedCompat'],
+        ]);
+        $this->objectManager->method('create')->willReturn($registry);
+        $resolver = new CompatModuleResolver($this->objectManager, FakeCompatModuleRegistry::class);
+
+        $this->assertSame(['Vendor_ModuleA', 'Vendor_ModuleB'], $resolver->getOriginalModules('Hyva_SharedCompat'));
+    }
+
+    public function testReturnsEmptyArrayForUnknownModule(): void
+    {
+        $registry = new FakeCompatModuleRegistry(['Vendor_Module' => ['Hyva_VendorCompat']]);
+        $this->objectManager->method('create')->willReturn($registry);
+        $resolver = new CompatModuleResolver($this->objectManager, FakeCompatModuleRegistry::class);
+
+        $this->assertSame([], $resolver->getOriginalModules('Vendor_Module'));
+        $this->assertSame([], $resolver->getOriginalModules('Unrelated_Module'));
+    }
+
+    public function testReturnsEmptyArrayWhenRegistryLacksExpectedMethods(): void
+    {
+        $this->objectManager->method('create')->willReturn(new \stdClass());
+        $resolver = new CompatModuleResolver($this->objectManager, \stdClass::class);
+
+        $this->assertSame([], $resolver->getOriginalModules('Some_Module'));
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/FakeCompatModuleRegistry.php b/tests/Unit/Service/TemplateOverride/FakeCompatModuleRegistry.php
new file mode 100644
index 00000000..9fbafe26
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/FakeCompatModuleRegistry.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+/**
+ * Stand-in for Hyvä's CompatModuleRegistry, which is not available in the unit test
+ * dependency set (Hyvä is an optional dependency resolved dynamically at runtime).
+ */
+class FakeCompatModuleRegistry
+{
+    /**
+     * @param array<string,array<int,string>> $origToCompatModules
+     */
+    public function __construct(
+        private readonly array $origToCompatModules = [],
+    ) {
+    }
+
+    /**
+     * Get all original module names with registered compat modules
+     *
+     * @return array<int,string>
+     */
+    public function getOrigModules(): array
+    {
+        return array_keys($this->origToCompatModules);
+    }
+
+    /**
+     * Get the compat modules registered for an original module
+     *
+     * @param string $originalModule
+     * @return array<int,string>
+     */
+    public function getCompatModulesFor(string $originalModule): array
+    {
+        return $this->origToCompatModules[$originalModule] ?? [];
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/FakeTheme.php b/tests/Unit/Service/TemplateOverride/FakeTheme.php
new file mode 100644
index 00000000..43548c87
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/FakeTheme.php
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\View\Design\ThemeInterface;
+
+/**
+ * Minimal ThemeInterface implementation for template override tests
+ */
+class FakeTheme implements ThemeInterface
+{
+    public function __construct(
+        private readonly string $code,
+        private readonly string $area = 'frontend',
+    ) {
+    }
+
+    public function getArea()
+    {
+        return $this->area;
+    }
+
+    public function getThemePath()
+    {
+        return $this->code;
+    }
+
+    public function getFullPath()
+    {
+        return $this->area . '/' . $this->code;
+    }
+
+    public function getParentTheme()
+    {
+        return null;
+    }
+
+    public function getCode()
+    {
+        return $this->code;
+    }
+
+    public function isPhysical()
+    {
+        return true;
+    }
+
+    public function getInheritedThemes()
+    {
+        return [];
+    }
+
+    public function getId()
+    {
+        return 1;
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/TemplateCopierTest.php b/tests/Unit/Service/TemplateOverride/TemplateCopierTest.php
new file mode 100644
index 00000000..e4d0efd2
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/TemplateCopierTest.php
@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\Filesystem\Driver\File;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateCopier;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class TemplateCopierTest extends TestCase
+{
+    private File&MockObject $fileDriver;
+    private TemplateCopier $copier;
+
+    protected function setUp(): void
+    {
+        $this->fileDriver = $this->createMock(File::class);
+        $this->copier = new TemplateCopier($this->fileDriver);
+    }
+
+    public function testCreatesMissingTargetDirectoryBeforeCopying(): void
+    {
+        $this->fileDriver->method('getParentDirectory')->with('/theme/M/templates/a/b.phtml')
+            ->willReturn('/theme/M/templates/a');
+        $this->fileDriver->method('isDirectory')->with('/theme/M/templates/a')->willReturn(false);
+        $this->fileDriver->expects($this->once())->method('createDirectory')->with('/theme/M/templates/a');
+        $this->fileDriver
+            ->expects($this->once())
+            ->method('copy')
+            ->with('/module/templates/a/b.phtml', '/theme/M/templates/a/b.phtml')
+            ->willReturn(true);
+
+        $this->copier->copy('/module/templates/a/b.phtml', '/theme/M/templates/a/b.phtml');
+    }
+
+    public function testDoesNotCreateExistingTargetDirectory(): void
+    {
+        $this->fileDriver->method('getParentDirectory')->willReturn('/theme/M/templates');
+        $this->fileDriver->method('isDirectory')->willReturn(true);
+        $this->fileDriver->expects($this->never())->method('createDirectory');
+        $this->fileDriver->expects($this->once())->method('copy')->willReturn(true);
+
+        $this->copier->copy('/source.phtml', '/theme/M/templates/target.phtml');
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/TemplateFallbackResolverTest.php b/tests/Unit/Service/TemplateOverride/TemplateFallbackResolverTest.php
new file mode 100644
index 00000000..6d72a01b
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/TemplateFallbackResolverTest.php
@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\Component\ComponentRegistrar;
+use Magento\Framework\Component\ComponentRegistrarInterface;
+use Magento\Framework\Filesystem\Driver\File;
+use Magento\Framework\ObjectManagerInterface;
+use Magento\Framework\View\Design\Fallback\Rule\RuleInterface;
+use Magento\Framework\View\Design\Fallback\RulePool;
+use Magento\Framework\View\DesignInterface;
+use OpenForgeProject\MageForge\Model\TemplateReference;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplateFallbackResolver;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class TemplateFallbackResolverTest extends TestCase
+{
+    private ObjectManagerInterface&MockObject $objectManager;
+    private DesignInterface&MockObject $design;
+    private ComponentRegistrarInterface&MockObject $componentRegistrar;
+    private File&MockObject $fileDriver;
+    private TemplateFallbackResolver $resolver;
+
+    protected function setUp(): void
+    {
+        $this->objectManager = $this->createMock(ObjectManagerInterface::class);
+        $this->design = $this->createMock(DesignInterface::class);
+        $this->componentRegistrar = $this->createMock(ComponentRegistrarInterface::class);
+        $this->fileDriver = $this->createMock(File::class);
+        $this->resolver = new TemplateFallbackResolver(
+            $this->objectManager,
+            $this->design,
+            $this->componentRegistrar,
+            $this->fileDriver,
+        );
+    }
+
+    public function testGetFallbackDirsUsesMagentoRuleAndSetsDesignTheme(): void
+    {
+        $theme = new FakeTheme('Vendor/theme');
+        $reference = new TemplateReference('Magento_Catalog', 'product/view/details.phtml');
+
+        $rule = $this->createMock(RuleInterface::class);
+        $rule->expects($this->once())
+            ->method('getPatternDirs')
+            ->with([
+                'area' => 'frontend',
+                'theme' => $theme,
+                'module_name' => 'Magento_Catalog',
+                'file' => 'product/view/details.phtml',
+            ])
+            ->willReturn([
+                '/theme/Magento_Catalog/templates',
+                '/compat/view/frontend/templates',
+                '/module/view/frontend/templates',
+                '/theme/Magento_Catalog/templates',
+            ]);
+
+        $rulePool = $this->createMock(RulePool::class);
+        $rulePool->method('getRule')->with(RulePool::TYPE_TEMPLATE_FILE)->willReturn($rule);
+
+        $this->objectManager->method('create')->with(RulePool::class)->willReturn($rulePool);
+        $this->design->expects($this->once())->method('setDesignTheme')->with($theme, 'frontend');
+
+        $dirs = $this->resolver->getFallbackDirs($reference, $theme);
+
+        $this->assertSame(
+            [
+                '/theme/Magento_Catalog/templates',
+                '/compat/view/frontend/templates',
+                '/module/view/frontend/templates',
+            ],
+            $dirs,
+            'Duplicate directories must be removed while preserving the fallback order',
+        );
+    }
+
+    public function testGetFallbackDirsFailsWhenRulePoolCannotBeCreated(): void
+    {
+        $this->objectManager->method('create')->willReturn(null);
+
+        $this->expectException(\RuntimeException::class);
+
+        $this->resolver->getFallbackDirs(new TemplateReference('A_B', 'x.phtml'), new FakeTheme('Vendor/theme'));
+    }
+
+    public function testFindFirstExistingFileReturnsFirstMatch(): void
+    {
+        $this->fileDriver
+            ->method('isFile')
+            ->willReturnCallback(static fn (string $path): bool => str_starts_with($path, '/module/'));
+
+        $result = $this->resolver->findFirstExistingFile(
+            ['/theme/Magento_Catalog/templates', '/module/view/frontend/templates'],
+            'product/view/details.phtml',
+        );
+
+        $this->assertSame('/module/view/frontend/templates/product/view/details.phtml', $result);
+    }
+
+    public function testFindFirstExistingFileSkipsExcludedDirectory(): void
+    {
+        $this->fileDriver->method('isFile')->willReturn(true);
+
+        $result = $this->resolver->findFirstExistingFile(
+            ['/theme/Magento_Catalog/templates', '/module/view/frontend/templates'],
+            'details.phtml',
+            '/theme/Magento_Catalog/templates',
+        );
+
+        $this->assertSame('/module/view/frontend/templates/details.phtml', $result);
+    }
+
+    public function testFindFirstExistingFileReturnsNullWhenNothingExists(): void
+    {
+        $this->fileDriver->method('isFile')->willReturn(false);
+
+        $result = $this->resolver->findFirstExistingFile(['/a', '/b'], 'details.phtml');
+
+        $this->assertNull($result);
+    }
+
+    public function testGetThemeTargetDirReturnsDirInsideTheme(): void
+    {
+        $theme = new FakeTheme('Vendor/theme');
+        $this->componentRegistrar
+            ->method('getPath')
+            ->with(ComponentRegistrar::THEME, 'frontend/Vendor/theme')
+            ->willReturn('/app/design/frontend/Vendor/theme');
+
+        $result = $this->resolver->getThemeTargetDir(
+            [
+                '/app/design/frontend/Vendor/theme/Magento_Catalog/templates',
+                '/module/view/frontend/templates',
+            ],
+            $theme,
+        );
+
+        $this->assertSame('/app/design/frontend/Vendor/theme/Magento_Catalog/templates', $result);
+    }
+
+    public function testGetThemeTargetDirReturnsNullForUnregisteredTheme(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn(null);
+
+        $this->assertNull($this->resolver->getThemeTargetDir(['/some/dir'], new FakeTheme('Vendor/theme')));
+    }
+
+    public function testGetThemeTargetDirReturnsNullWhenNoDirIsInsideTheme(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/app/design/frontend/Vendor/theme');
+
+        $result = $this->resolver->getThemeTargetDir(
+            ['/module/view/frontend/templates', '/app/design/frontend/Vendor/other-theme/Magento_Catalog/templates'],
+            new FakeTheme('Vendor/theme'),
+        );
+
+        $this->assertNull($result);
+    }
+}
diff --git a/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php b/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php
new file mode 100644
index 00000000..c11b50bb
--- /dev/null
+++ b/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php
@@ -0,0 +1,281 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Test\Unit\Service\TemplateOverride;
+
+use Magento\Framework\App\Filesystem\DirectoryList;
+use Magento\Framework\Component\ComponentRegistrar;
+use Magento\Framework\Component\ComponentRegistrarInterface;
+use Magento\Framework\Filesystem\Driver\File;
+use OpenForgeProject\MageForge\Service\TemplateOverride\CompatModuleResolver;
+use OpenForgeProject\MageForge\Service\TemplateOverride\TemplatePathParser;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class TemplatePathParserTest extends TestCase
+{
+    private ComponentRegistrarInterface&MockObject $componentRegistrar;
+    private CompatModuleResolver&MockObject $compatModuleResolver;
+    private File&MockObject $fileDriver;
+    private DirectoryList&MockObject $directoryList;
+    private TemplatePathParser $parser;
+
+    protected function setUp(): void
+    {
+        $this->componentRegistrar = $this->createMock(ComponentRegistrarInterface::class);
+        $this->compatModuleResolver = $this->createMock(CompatModuleResolver::class);
+        $this->fileDriver = $this->createMock(File::class);
+        $this->directoryList = $this->createMock(DirectoryList::class);
+        $this->directoryList->method('getRoot')->willReturn('/magento');
+        $this->parser = new TemplatePathParser(
+            $this->componentRegistrar,
+            $this->compatModuleResolver,
+            $this->fileDriver,
+            $this->directoryList,
+        );
+    }
+
+    public function testParsesModuleNotation(): void
+    {
+        $this->componentRegistrar
+            ->method('getPath')
+            ->with(ComponentRegistrar::MODULE, 'Magento_Catalog')
+            ->willReturn('/magento/vendor/magento/module-catalog');
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse('Magento_Catalog::product/view/details.phtml');
+
+        $this->assertSame('Magento_Catalog', $reference->getModuleName());
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
+    public function testNormalizesLeadingSlashesAndBackslashesInModuleNotation(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/module');
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse('Vendor_Module::/product\\view/details.phtml');
+
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
+    public function testRejectsEmptyInput(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Template reference must not be empty.');
+
+        $this->parser->parse('   ');
+    }
+
+    public function testRejectsModuleNotationWithoutPath(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Expected format: Module_Name::path/to/template.phtml');
+
+        $this->parser->parse('Magento_Catalog::');
+    }
+
+    public function testRejectsUnknownModule(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn(null);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage("Module 'Unknown_Module' is not registered");
+
+        $this->parser->parse('Unknown_Module::some/template.phtml');
+    }
+
+    public function testRejectsRelativePathSegments(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('must not contain relative path segments');
+
+        $this->parser->parse('Magento_Catalog::../../../etc/env.phtml');
+    }
+
+    public function testMapsCompatModuleNotationToOriginalModule(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/compat-module');
+        $this->compatModuleResolver
+            ->method('getOriginalModules')
+            ->with('Hyva_AmastyLabelCompat')
+            ->willReturn(['Amasty_Label']);
+
+        $reference = $this->parser->parse('Hyva_AmastyLabelCompat::label/product.phtml');
+
+        $this->assertSame('Amasty_Label', $reference->getModuleName());
+        $this->assertSame('label/product.phtml', $reference->getTemplatePath());
+        $this->assertSame('Amasty_Label::label/product.phtml', $reference->getTemplateId());
+    }
+
+    public function testStripsOriginalModuleDirectoryFromCompatTemplatePath(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/compat-module');
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn(['Amasty_Label']);
+
+        $reference = $this->parser->parse('Hyva_AmastyLabelCompat::Amasty_Label/label/product.phtml');
+
+        $this->assertSame('Amasty_Label', $reference->getModuleName());
+        $this->assertSame('label/product.phtml', $reference->getTemplatePath());
+    }
+
+    public function testRejectsAmbiguousCompatModuleWithoutModuleDirectory(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/compat-module');
+        $this->compatModuleResolver
+            ->method('getOriginalModules')
+            ->willReturn(['Vendor_ModuleA', 'Vendor_ModuleB']);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('compatibility module for several modules');
+
+        $this->parser->parse('Hyva_SharedCompat::some/template.phtml');
+    }
+
+    public function testResolvesAmbiguousCompatModuleViaModuleDirectoryPrefix(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/compat-module');
+        $this->compatModuleResolver
+            ->method('getOriginalModules')
+            ->willReturn(['Vendor_ModuleA', 'Vendor_ModuleB']);
+
+        $reference = $this->parser->parse('Hyva_SharedCompat::Vendor_ModuleB/some/template.phtml');
+
+        $this->assertSame('Vendor_ModuleB', $reference->getModuleName());
+        $this->assertSame('some/template.phtml', $reference->getTemplatePath());
+    }
+
+    public function testParsesModuleFilePath(): void
+    {
+        $file = '/magento/vendor/magento/module-catalog/view/frontend/templates/product/view/details.phtml';
+        $this->fileDriver->method('isFile')->with($file)->willReturn(true);
+        $this->fileDriver->method('getRealPath')->with($file)->willReturn($file);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->with(ComponentRegistrar::MODULE)
+            ->willReturn(['Magento_Catalog' => '/magento/vendor/magento/module-catalog']);
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse($file);
+
+        $this->assertSame('Magento_Catalog', $reference->getModuleName());
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
+    public function testParsesCompatModuleFilePathToOriginalModule(): void
+    {
+        $file = '/magento/vendor/hyva-themes/compat/src/view/frontend/templates/label/product.phtml';
+        $this->fileDriver->method('isFile')->willReturn(true);
+        $this->fileDriver->method('getRealPath')->willReturn($file);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->with(ComponentRegistrar::MODULE)
+            ->willReturn(['Hyva_AmastyLabelCompat' => '/magento/vendor/hyva-themes/compat/src']);
+        $this->compatModuleResolver
+            ->method('getOriginalModules')
+            ->with('Hyva_AmastyLabelCompat')
+            ->willReturn(['Amasty_Label']);
+
+        $reference = $this->parser->parse($file);
+
+        $this->assertSame('Amasty_Label::label/product.phtml', $reference->getTemplateId());
+    }
+
+    public function testParsesThemeFilePath(): void
+    {
+        $file = '/magento/app/design/frontend/Vendor/theme/Magento_Catalog/templates/product/view/details.phtml';
+        $this->fileDriver->method('isFile')->willReturn(true);
+        $this->fileDriver->method('getRealPath')->willReturn($file);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->willReturnMap([
+                [ComponentRegistrar::MODULE, []],
+                [ComponentRegistrar::THEME, ['frontend/Vendor/theme' => '/magento/app/design/frontend/Vendor/theme']],
+            ]);
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse($file);
+
+        $this->assertSame('Magento_Catalog', $reference->getModuleName());
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
+    public function testUsesLongestComponentPathMatch(): void
+    {
+        $file = '/magento/vendor/acme/module-base/sub-module/view/frontend/templates/widget.phtml';
+        $this->fileDriver->method('isFile')->willReturn(true);
+        $this->fileDriver->method('getRealPath')->willReturn($file);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->with(ComponentRegistrar::MODULE)
+            ->willReturn([
+                'Acme_Base' => '/magento/vendor/acme/module-base',
+                'Acme_Sub' => '/magento/vendor/acme/module-base/sub-module',
+            ]);
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse($file);
+
+        $this->assertSame('Acme_Sub', $reference->getModuleName());
+        $this->assertSame('widget.phtml', $reference->getTemplatePath());
+    }
+
+    public function testResolvesRelativePathAgainstMagentoRoot(): void
+    {
+        $relative = 'vendor/magento/module-catalog/view/frontend/templates/product/view/details.phtml';
+        $absolute = '/magento/' . $relative;
+        $this->fileDriver
+            ->method('isFile')
+            ->willReturnCallback(static fn (string $path): bool => $path === $absolute);
+        $this->fileDriver->method('getRealPath')->with($absolute)->willReturn($absolute);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->with(ComponentRegistrar::MODULE)
+            ->willReturn(['Magento_Catalog' => '/magento/vendor/magento/module-catalog']);
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse($relative);
+
+        $this->assertSame('Magento_Catalog::product/view/details.phtml', $reference->getTemplateId());
+    }
+
+    public function testRejectsMissingFile(): void
+    {
+        $this->fileDriver->method('isFile')->willReturn(false);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage("Template file '/nowhere/file.phtml' not found");
+
+        $this->parser->parse('/nowhere/file.phtml');
+    }
+
+    public function testRejectsModuleFileOutsideTemplatesDirectory(): void
+    {
+        $file = '/magento/vendor/magento/module-catalog/view/frontend/layout/default.xml';
+        $this->fileDriver->method('isFile')->willReturn(true);
+        $this->fileDriver->method('getRealPath')->willReturn($file);
+        $this->componentRegistrar
+            ->method('getPaths')
+            ->with(ComponentRegistrar::MODULE)
+            ->willReturn(['Magento_Catalog' => '/magento/vendor/magento/module-catalog']);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('not inside a view/<area>/templates directory');
+
+        $this->parser->parse($file);
+    }
+
+    public function testRejectsFileOutsideAnyComponent(): void
+    {
+        $file = '/magento/pub/media/some-file.phtml';
+        $this->fileDriver->method('isFile')->willReturn(true);
+        $this->fileDriver->method('getRealPath')->willReturn($file);
+        $this->componentRegistrar->method('getPaths')->willReturn([]);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('does not belong to a registered module or theme');
+
+        $this->parser->parse($file);
+    }
+}

From fac76f53bd3282db84f676be01b6d67a412f54bb Mon Sep 17 00:00:00 2001
From: Thomas Hauschild <7961978+Morgy93@users.noreply.github.com>
Date: Thu, 9 Jul 2026 08:08:52 +0200
Subject: [PATCH 2/2] feat: add template override command and improve
 validation

---
 .github/workflows/magento-compatibility.yml   |  2 ++
 .../Command/Template/OverrideCommand.php      |  9 ++++++-
 .../TemplateOverride/TemplatePathParser.php   | 17 +++++++++---
 .../Command/Template/OverrideCommandTest.php  | 24 +++++++++++++++++
 .../TemplatePathParserTest.php                | 26 +++++++++++++++++++
 5 files changed, 73 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/magento-compatibility.yml b/.github/workflows/magento-compatibility.yml
index a4b8fdf6..a4790589 100644
--- a/.github/workflows/magento-compatibility.yml
+++ b/.github/workflows/magento-compatibility.yml
@@ -145,6 +145,7 @@ jobs:
           bin/magento mageforge:theme:watch --help
           bin/magento mageforge:theme:clean --help
           bin/magento mageforge:theme:inspector --help
+          bin/magento mageforge:template:override --help
           bin/magento mageforge:hyva:compatibility:check --help
           bin/magento mageforge:hyva:tokens --help
 
@@ -160,6 +161,7 @@ jobs:
           bin/magento frontend:build --help
           bin/magento frontend:watch --help
           bin/magento frontend:clean --help
+          bin/magento template:override --help
           bin/magento hyva:check --help
           bin/magento hyva:tokens --help
 
diff --git a/src/Console/Command/Template/OverrideCommand.php b/src/Console/Command/Template/OverrideCommand.php
index e805f84e..44d21046 100644
--- a/src/Console/Command/Template/OverrideCommand.php
+++ b/src/Console/Command/Template/OverrideCommand.php
@@ -200,7 +200,14 @@ protected function executeCommand(InputInterface $input, OutputInterface $output
             return Cli::RETURN_FAILURE;
         }
 
-        $this->cacheCleaner->clean($this->io, $this->isVerbose($output));
+        if (!$this->cacheCleaner->clean($this->io, $this->isVerbose($output))) {
+            $this->io->warning(sprintf(
+                'Template override created at %s, but cleaning the caches failed. '
+                . "Run 'bin/magento cache:clean full_page block_html layout translate' manually.",
+                $this->toRelativePath($targetFile),
+            ));
+            return Cli::RETURN_FAILURE;
+        }
 
         $this->io->success(sprintf('Template override created: %s', $this->toRelativePath($targetFile)));
         return Cli::RETURN_SUCCESS;
diff --git a/src/Service/TemplateOverride/TemplatePathParser.php b/src/Service/TemplateOverride/TemplatePathParser.php
index 816d1502..ef23f165 100644
--- a/src/Service/TemplateOverride/TemplatePathParser.php
+++ b/src/Service/TemplateOverride/TemplatePathParser.php
@@ -273,17 +273,26 @@ private function createReference(string $moduleName, string $templatePath): Temp
     /**
      * Normalize a template path and reject relative path segments
      *
+     * The path is later concatenated into a filesystem target, so any "." or ".." segment
+     * is rejected explicitly to prevent directory traversal; repeated slashes are collapsed.
+     *
      * @param string $path
      * @return string
      * @throws \InvalidArgumentException
      */
     private function normalizeTemplatePath(string $path): string
     {
-        $normalized = ltrim(trim(str_replace('\\', '/', $path)), '/');
-        if (str_contains($normalized, './')) {
-            throw new \InvalidArgumentException("Template path '$path' must not contain relative path segments.");
+        $segments = [];
+        foreach (explode('/', trim(str_replace('\\', '/', $path))) as $segment) {
+            if ($segment === '') {
+                continue;
+            }
+            if ($segment === '.' || $segment === '..') {
+                throw new \InvalidArgumentException("Template path '$path' must not contain relative path segments.");
+            }
+            $segments[] = $segment;
         }
 
-        return $normalized;
+        return implode('/', $segments);
     }
 }
diff --git a/tests/Unit/Console/Command/Template/OverrideCommandTest.php b/tests/Unit/Console/Command/Template/OverrideCommandTest.php
index d6ee5350..e75f38ed 100644
--- a/tests/Unit/Console/Command/Template/OverrideCommandTest.php
+++ b/tests/Unit/Console/Command/Template/OverrideCommandTest.php
@@ -246,6 +246,30 @@ public function testForceReplacesExistingOverrideFromNextFallbackSource(): void
         $this->assertStringContainsString('Template override created:', $display);
     }
 
+    public function testFailsWithWarningWhenCacheCleaningFails(): void
+    {
+        $this->setUpResolvableTemplate();
+        $this->fallbackResolver
+            ->method('findFirstExistingFile')
+            ->willReturnOnConsecutiveCalls(
+                self::MODULE_DIR . '/product/view/details.phtml',
+                self::THEME_DIR . '/product/view/details.phtml',
+            );
+        $this->templateCopier->expects($this->once())->method('copy');
+        $this->cacheCleaner->method('clean')->willReturn(false);
+
+        $tester = new CommandTester($this->command);
+        $exitCode = $tester->execute([
+            'template' => 'Magento_Catalog::product/view/details.phtml',
+            '--theme' => 'Vendor/theme',
+        ]);
+
+        $this->assertSame(Cli::RETURN_FAILURE, $exitCode);
+        $display = (string) preg_replace('/\s+/', ' ', $tester->getDisplay());
+        $this->assertStringContainsString('cleaning the caches failed', $display);
+        $this->assertStringNotContainsString('Template override created:', $display);
+    }
+
     public function testFailsWhenTemplateIsNotFoundInAnyFallbackLocation(): void
     {
         $this->setUpResolvableTemplate();
diff --git a/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php b/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php
index c11b50bb..c99a5147 100644
--- a/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php
+++ b/tests/Unit/Service/TemplateOverride/TemplatePathParserTest.php
@@ -94,6 +94,32 @@ public function testRejectsRelativePathSegments(): void
         $this->parser->parse('Magento_Catalog::../../../etc/env.phtml');
     }
 
+    public function testRejectsTrailingParentDirectorySegment(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('must not contain relative path segments');
+
+        $this->parser->parse('Magento_Catalog::product/..');
+    }
+
+    public function testRejectsCurrentDirectorySegment(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('must not contain relative path segments');
+
+        $this->parser->parse('Magento_Catalog::product/./details.phtml');
+    }
+
+    public function testCollapsesRepeatedSlashesInTemplatePath(): void
+    {
+        $this->componentRegistrar->method('getPath')->willReturn('/path/to/module');
+        $this->compatModuleResolver->method('getOriginalModules')->willReturn([]);
+
+        $reference = $this->parser->parse('Magento_Catalog::product//view///details.phtml');
+
+        $this->assertSame('product/view/details.phtml', $reference->getTemplatePath());
+    }
+
     public function testMapsCompatModuleNotationToOriginalModule(): void
     {
         $this->componentRegistrar->method('getPath')->willReturn('/path/to/compat-module');