feat: implement SymlinkCleaner service and integrate into theme builders #88

Author: dermatz

src/Service/SymlinkCleaner.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenForgeProject\MageForge\Service;
+
+use Magento\Framework\App\State;
+use Magento\Framework\Filesystem\Driver\File;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+/**
+ * Service for cleaning symlinks in theme CSS directories
+ *
+ * In developer mode, symlinks in {theme}/web/css/ can cause issues during
+ * the build process. This service detects and removes all symlinks before
+ * the build starts to ensure a clean workflow.
+ */
+class SymlinkCleaner
+{
+    public function __construct(
+        private readonly File $fileDriver,
+        private readonly State $state
+    ) {
+    }
+
+    /**
+     * Remove all symlinks from {theme}/web/css/ directory in developer mode
+     *
+     * @param string $themePath Path to theme directory
+     * @param SymfonyStyle $io Symfony style output
+     * @param bool $isVerbose Whether to show verbose output
+     * @return bool True on success or if no action needed, false on error
+     */
+    public function cleanSymlinks(
+        string $themePath,
+        SymfonyStyle $io,
+        bool $isVerbose
+    ): bool {
+        try {
+            // Only clean symlinks in developer mode
+            if ($this->state->getMode() !== State::MODE_DEVELOPER) {
+                return true;
+            }
+
+            $cssPath = rtrim($themePath, '/') . '/web/css';
+
+            // Nothing to clean if directory doesn't exist
+            if (!$this->fileDriver->isDirectory($cssPath)) {
+                return true;
+            }
+
+            $items = $this->fileDriver->readDirectory($cssPath);
+            $deletedCount = 0;
+
+            foreach ($items as $item) {
+                // Check if item is a symlink
+                if (is_link($item)) {
+                    $this->fileDriver->deleteFile($item);
+                    $deletedCount++;
+
+                    if ($isVerbose) {
+                        $io->writeln(sprintf(
+                            '  <fg=yellow>⚠</> Removed symlink: %s',
+                            basename($item)
+                        ));
+                    }
+                }
+            }
+
+            if ($deletedCount > 0 && $isVerbose) {
+                $io->success(sprintf(
+                    'Removed %d symlink(s) from web/css/',
+                    $deletedCount
+                ));
+            }
+
+            return true;
+        } catch (\Exception $e) {
+            // Don't fail the build process if symlink cleanup fails
+            // Just warn the user and continue
+            if ($isVerbose) {
+                $io->warning(sprintf(
+                    'Could not clean symlinks: %s',
+                    $e->getMessage()
+                ));
+            }
+            return true;
+        }
+    }
+}

src/Service/ThemeBuilder/HyvaThemes/Builder.php

@@ -9,6 +9,7 @@
 use OpenForgeProject\MageForge\Service\CacheCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentDeployer;
+use OpenForgeProject\MageForge\Service\SymlinkCleaner;
 use OpenForgeProject\MageForge\Service\ThemeBuilder\BuilderInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
@@ -22,7 +23,8 @@ public function __construct(
         private readonly File $fileDriver,
         private readonly StaticContentDeployer $staticContentDeployer,
         private readonly StaticContentCleaner $staticContentCleaner,
-        private readonly CacheCleaner $cacheCleaner
+        private readonly CacheCleaner $cacheCleaner,
+        private readonly SymlinkCleaner $symlinkCleaner
     ) {
     }
 
@@ -71,6 +73,11 @@ public function build(string $themeCode, string $themePath, SymfonyStyle $io, Ou
             return false;
         }
 
+        // Clean symlinks in web/css/ directory before build
+        if (!$this->symlinkCleaner->cleanSymlinks($themePath, $io, $isVerbose)) {
+            return false;
+        }
+
         if (!$this->generateHyvaConfig($io, $isVerbose)) {
             return false;
         }

src/Service/ThemeBuilder/MagentoStandard/Builder.php

@@ -9,6 +9,7 @@
 use OpenForgeProject\MageForge\Service\CacheCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentDeployer;
+use OpenForgeProject\MageForge\Service\SymlinkCleaner;
 use OpenForgeProject\MageForge\Service\ThemeBuilder\BuilderInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
@@ -22,7 +23,8 @@ public function __construct(
         private readonly File $fileDriver,
         private readonly StaticContentDeployer $staticContentDeployer,
         private readonly StaticContentCleaner $staticContentCleaner,
-        private readonly CacheCleaner $cacheCleaner
+        private readonly CacheCleaner $cacheCleaner,
+        private readonly SymlinkCleaner $symlinkCleaner
     ) {
     }
 
@@ -52,6 +54,11 @@ public function build(string $themeCode, string $themePath, SymfonyStyle $io, Ou
             return false;
         }
 
+        // Clean symlinks in web/css/ directory before build
+        if (!$this->symlinkCleaner->cleanSymlinks($themePath, $io, $isVerbose)) {
+            return false;
+        }
+
         // Run grunt tasks
         try {
             if ($isVerbose) {

src/Service/ThemeBuilder/TailwindCSS/Builder.php

@@ -9,6 +9,7 @@
 use OpenForgeProject\MageForge\Service\CacheCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentCleaner;
 use OpenForgeProject\MageForge\Service\StaticContentDeployer;
+use OpenForgeProject\MageForge\Service\SymlinkCleaner;
 use OpenForgeProject\MageForge\Service\ThemeBuilder\BuilderInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
@@ -22,7 +23,8 @@ public function __construct(
         private readonly File $fileDriver,
         private readonly StaticContentDeployer $staticContentDeployer,
         private readonly StaticContentCleaner $staticContentCleaner,
-        private readonly CacheCleaner $cacheCleaner
+        private readonly CacheCleaner $cacheCleaner,
+        private readonly SymlinkCleaner $symlinkCleaner
     ) {
     }
 
@@ -71,6 +73,11 @@ public function build(string $themeCode, string $themePath, SymfonyStyle $io, Ou
             return false;
         }
 
+        // Clean symlinks in web/css/ directory before build
+        if (!$this->symlinkCleaner->cleanSymlinks($themePath, $io, $isVerbose)) {
+            return false;
+        }
+
         // Build Hyva theme
         $tailwindPath = rtrim($themePath, '/') . '/web/tailwind';
         if (!$this->fileDriver->isDirectory($tailwindPath)) {

src/etc/di.xml

@@ -56,4 +56,12 @@
                   <argument name="themeCleaner" xsi:type="object">OpenForgeProject\MageForge\Service\ThemeCleaner</argument>
             </arguments>
       </type>
+
+      <!-- Configure SymlinkCleaner Service -->
+      <type name="OpenForgeProject\MageForge\Service\SymlinkCleaner">
+            <arguments>
+                  <argument name="fileDriver" xsi:type="object">Magento\Framework\Filesystem\Driver\File</argument>
+                  <argument name="state" xsi:type="object">Magento\Framework\App\State</argument>
+            </arguments>
+      </type>
 </config>