feat: add Node.js/Grunt setup check and improve build process for gruntless themes like backend-theme

Author: dermatz

docs/advanced_usage.md

@@ -37,10 +37,30 @@ This document provides detailed information and advanced tips for using MageForg
 ### Standard Magento Themes (LESS)
 
 For traditional LESS-based Magento themes, MageForge handles:
-- LESS compilation
+- LESS compilation via Grunt
 - Source map generation
 - Minification for production
 
+#### Themes Without Node.js/Grunt Setup
+
+MageForge automatically detects if a Magento Standard theme intentionally omits Node.js/Grunt setup. If none of the following files exist:
+- `package.json`
+- `package-lock.json`
+- `gruntfile.js`
+- `grunt-config.json`
+
+The builder will skip all Node/Grunt-related steps and only:
+- Clean static content (if in developer mode)
+- Deploy static content
+- Clean cache
+
+This is useful for:
+- Themes that use pre-compiled CSS
+- Minimal themes without custom LESS
+- Simple theme inheritance without asset compilation
+
+**Note**: Watch mode requires Node.js/Grunt setup and will return an error if these files are missing.
+
 ### Hyvä Themes (Tailwind CSS)
 
 MageForge streamlines Hyvä theme development with:

docs/commands.md

@@ -470,6 +470,9 @@ The commands rely on several services for their functionality:
 - `BuilderPool`: Manages theme builders and selects appropriate builders for themes
 - `BuilderInterface`: Implemented by all theme builders
 - `MagentoStandard\Builder`: Processes standard Magento LESS-based themes
+  - Automatically detects if Node.js/Grunt setup is present
+  - Skips Node/Grunt steps if intentionally omitted (no package.json, package-lock.json, gruntfile.js or grunt-config.json)
+  - Only performs static content deployment and cache cleaning for themes without build tools
 - Various other builders for different theme types
 
 ### Theme Services

docs/custom_theme_builders.md

@@ -308,6 +308,50 @@ public function autoRepair(string $themePath, SymfonyStyle $io, OutputInterface
 }
 ```
 
+### Best Practice: Optional Build Tool Setup
+
+If your builder uses optional build tools (like Node.js, Grunt, Webpack), consider checking if the setup exists before requiring it. This allows themes to intentionally skip certain build steps:
+
+```php
+private function hasNodeSetup(): bool
+{
+    $rootPath = '.';
+
+    return $this->fileDriver->isExists($rootPath . '/package.json')
+        || $this->fileDriver->isExists($rootPath . '/package-lock.json')
+        || $this->fileDriver->isExists($rootPath . '/gruntfile.js')
+        || $this->fileDriver->isExists($rootPath . '/grunt-config.json');
+}
+
+public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
+{
+    if (!$this->detect($themePath)) {
+        return false;
+    }
+
+    // Check if Node/Grunt setup is intentionally absent
+    $hasNodeSetup = $this->hasNodeSetup();
+
+    if ($hasNodeSetup) {
+        // Run Node/Grunt build steps
+        if (!$this->autoRepair($themePath, $io, $output, $isVerbose)) {
+            return false;
+        }
+
+        // Execute build commands...
+    } else {
+        if ($isVerbose) {
+            $io->note('No Node.js setup detected. Skipping Node/Grunt steps.');
+        }
+    }
+
+    // Continue with other build steps (deploy, cache, etc.)
+    return true;
+}
+```
+
+This approach allows themes to work without specific build tools while still supporting full builds when they are present.
+
 ### The watch() Method
 
 This method starts a process that monitors changes to theme files and automatically rebuilds when necessary:

src/Service/ThemeBuilder/MagentoStandard/Builder.php

@@ -52,37 +52,46 @@ public function build(string $themeCode, string $themePath, SymfonyStyle $io, Ou
             return false;
         }
 
-        if (!$this->autoRepair($themePath, $io, $output, $isVerbose)) {
-            return false;
-        }
-
-        // Clean symlinks in web/css/ directory before build
-        if (!$this->symlinkCleaner->cleanSymlinks($themePath, $io, $isVerbose)) {
-            return false;
-        }
+        // Check if Node/Grunt setup is intentionally absent
+        $hasNodeSetup = $this->hasNodeSetup();
 
-        // Run grunt tasks
-        try {
-            if ($isVerbose) {
-                $io->text('Running grunt clean...');
-                $this->shell->execute('node_modules/.bin/grunt clean');
-            } else {
-                $this->shell->execute('node_modules/.bin/grunt clean --quiet');
+        if ($hasNodeSetup) {
+            if (!$this->autoRepair($themePath, $io, $output, $isVerbose)) {
+                return false;
             }
 
-            if ($isVerbose) {
-                $io->text('Running grunt less...');
-                $this->shell->execute('node_modules/.bin/grunt less');
-            } else {
-                $this->shell->execute('node_modules/.bin/grunt less --quiet');
+            // Clean symlinks in web/css/ directory before build
+            if (!$this->symlinkCleaner->cleanSymlinks($themePath, $io, $isVerbose)) {
+                return false;
             }
 
-            if ($isVerbose) {
-                $io->success('Grunt tasks completed successfully.');
+            // Run grunt tasks
+            try {
+                if ($isVerbose) {
+                    $io->text('Running grunt clean...');
+                    $this->shell->execute('node_modules/.bin/grunt clean');
+                } else {
+                    $this->shell->execute('node_modules/.bin/grunt clean --quiet');
+                }
+
+                if ($isVerbose) {
+                    $io->text('Running grunt less...');
+                    $this->shell->execute('node_modules/.bin/grunt less');
+                } else {
+                    $this->shell->execute('node_modules/.bin/grunt less --quiet');
+                }
+
+                if ($isVerbose) {
+                    $io->success('Grunt tasks completed successfully.');
+                }
+            } catch (\Exception $e) {
+                $io->error('Failed to run grunt tasks: ' . $e->getMessage());
+                return false;
+            }
+        } else {
+            if (!$isVerbose) {
+                $io->success('No Grunt-Setup detected. Skipping Magento Grunt steps.');
             }
-        } catch (\Exception $e) {
-            $io->error('Failed to run grunt tasks: ' . $e->getMessage());
-            return false;
         }
 
         // Deploy static content
@@ -177,6 +186,12 @@ public function watch(string $themeCode, string $themePath, SymfonyStyle $io, Ou
             return false;
         }
 
+        // Check if Node/Grunt setup is intentionally absent
+        if (!$this->hasNodeSetup()) {
+            $io->error('Watch mode requires Node.js/Grunt setup. No package.json, package-lock.json, node_modules, or grunt-config.json found.');
+            return false;
+        }
+
         // Clean static content if in developer mode
         if (!$this->staticContentCleaner->cleanIfNeeded($themeCode, $io, $output, $isVerbose)) {
             return false;
@@ -213,4 +228,21 @@ public function getName(): string
     {
         return self::THEME_NAME;
     }
+
+    /**
+     * Check if Node.js/Grunt setup exists
+     *
+     * Returns true if at least one of the required files exists
+     *
+     * @return bool
+     */
+    private function hasNodeSetup(): bool
+    {
+        $rootPath = '.';
+
+        return $this->fileDriver->isExists($rootPath . '/package.json')
+            || $this->fileDriver->isExists($rootPath . '/package-lock.json')
+            || $this->fileDriver->isExists($rootPath . '/gruntfile.js')
+            || $this->fileDriver->isExists($rootPath . '/grunt-config.json');
+    }
 }