### Start DDEV Environment

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Start the DDEV environment to pull necessary containers and configure the local development setup. This command prepares the Docker environment for MageForge.

```bash
ddev start
```

--------------------------------

### Install Magento 2 with MageForge

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Install a fresh Magento 2 instance, including sample data, and register the MageForge module. This script also enables the module and sets the environment to developer mode.

```bash
ddev install-magento
```

--------------------------------

### Enable MageForge Module

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

After installation, enable the MageForge module and run Magento's setup upgrade command to apply necessary database schema changes.

```bash
bin/magento module:enable OpenForgeProject_MageForge
bin/magento setup:upgrade
```

--------------------------------

### Example: Displaying All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Iterates through all themes obtained from getAllThemes() and prints their path, code, and title. This is useful for debugging or displaying a theme directory.

```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

foreach ($themes as $path => $theme) {
    echo "Path: $path\n";
    echo "Code: " . $theme->getCode() . "\n";
    echo "Title: " . $theme->getThemeTitle() . "\n";
    echo "---\n";
}

// Output:
// Path: frontend/Magento/luma
// Code: Magento/luma
// Title: Magento Luma
// ---
// Path: frontend/MyVendor/custom
// Code: MyVendor/custom
// Title: My Custom Theme
// ---

```

--------------------------------

### Theme Build Workflow Implementation

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Example of how to integrate BuilderPool into a theme build workflow. It gets the appropriate builder, checks for its existence, and then executes the build method, throwing exceptions on failure.

```php
public function buildTheme(string $themeCode, string $themePath) {
    $builder = $this->builderPool->getBuilder($themePath);
    
    if ($builder === null) {
        throw new \RuntimeException("No suitable builder found for theme");
    }
    
    if (!$builder->build($themeCode, $themePath, $this->io, $this->output, $isVerbose)) {
        throw new \RuntimeException("Theme build failed");
    }
    
    return "Theme built with " . $builder->getName();
}
```

--------------------------------

### autoRepair()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Repair missing dependencies or perform setup prior to build. This method ensures that the theme environment is ready for the build process.

```APIDOC
## autoRepair()

### Description
Repair missing dependencies or perform setup prior to build. This includes checking for and installing Node modules, validating Grunt setup, etc.

### Method
```php
public function autoRepair(
    string $themePath,
    SymfonyStyle $io,
    OutputInterface $output,
    bool $isVerbose,
): bool
```

### Parameters
#### Path Parameters
- **themePath** (string) - Yes - Absolute path to the theme directory
- **io** (SymfonyStyle) - Yes - Symfony console style for output
- **output** (OutputInterface) - Yes - Console output interface
- **isVerbose** (bool) - Yes - Flag to show verbose output

### Return Type
`bool`

Returns `true` if all dependencies are satisfied or were successfully repaired, `false` on error.

### Repair Operations (by builder type):
- **HyvaThemes & TailwindCSS:** Install Node modules, check for outdated packages
- **MagentoStandard:** Install Node modules, install Grunt CLI globally if missing

### Example
```php
$builder = $builderPool->getBuilder($themePath);
if (!$builder->autoRepair($themePath, $io, $output, true)) {
    echo "Failed to repair dependencies";
    return false;
}
```
```

--------------------------------

### Usage: List All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

A basic example of how to instantiate ThemeList and iterate through all themes, printing their code and title. Includes a check for an empty theme list.

```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

if (empty($themes)) {
    echo "No themes found";
    return;
}

foreach ($themes as $theme) {
    echo $theme->getCode() . " - " . $theme->getThemeTitle();
}

```

--------------------------------

### Listing Available Builders and Creating Them

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderFactory.md

Illustrates how to get a list of all registered builder names and then iterate through them to create and potentially use each builder. This is useful for introspection or advanced management.

```php
$available = $factory->getAvailableBuilders();
// Output: ["HyvaThemes", "TailwindCSS", "MagentoStandard"]

foreach ($available as $builderName) {
    $builder = $factory->create($builderName);
    echo "Builder: " . $builder->getName();
}
```

--------------------------------

### Get All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Retrieves all installed themes in the Magento system. Use this to get a complete list of themes for iteration or further processing.

```php
public function getAllThemes(): array<string, Theme>
```

--------------------------------

### Implement a Custom File Watcher

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Starts a custom watcher script for theme files. Ensure the watcher script exists at the specified path.

```php
public function watch(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Examples of watch implementations:

    // 1. Start your custom watcher
    try {
        $command = 'node ' . $themePath . '/your-watcher.js';
        if ($isVerbose) {
            $io->text('Starting watch process with: ' . $command);
        }
        exec($command);
    } catch (\Exception $e) {
        $io->error('Watch process could not be started: ' . $e->getMessage());
        return false;
    }

    // 2. Use existing tools
    try {
        exec('cd ' . $themePath . ' && npm run watch');
    } catch (\Exception $e) {
        $io->error('Watch process could not be started: ' . $e->getMessage());
        return false;
    }

    return true;
}
```

--------------------------------

### Check for Node.js Setup

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

This private helper method checks if a Node.js setup (package.json, package-lock.json, gruntfile.js, grunt-config.json) exists in the theme's root path. It's used to conditionally execute Node.js related 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');
}
```

--------------------------------

### Sample Configuration Data

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/configuration.md

Example data illustrating how MageForge configuration settings are stored in the core_config_data table, showing scope, scope_id, path, and value.

```sql
scope,scope_id,path,value
websites,0,mageforge/inspector/theme,dark
websites,0,mageforge/inspector/position,bottom-left
stores,1,dev/mageforge_inspector/enabled,1
stores,1,mageforge/inspector/show_button_labels,1
stores,1,mageforge/inspector/show_health_score,1

```

--------------------------------

### Advanced BuilderFactory Usage Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderFactory.md

An example demonstrating advanced, internal use of BuilderFactory, including adding a builder and retrieving it by name. This is typically handled by dependency injection and BuilderPool.

```php
// Get the correct builder by type name
$factory = new BuilderFactory();
$factory->addBuilder(new HyvaThemes\Builder(...));

// Retrieve by name
$builder = $factory->create('HyvaThemes');

// List all registered builders
$names = $factory->getAvailableBuilders();
```

--------------------------------

### List Magento Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Lists all available Magento themes in the installation. Use this command to see all themes recognized by Magento.

```bash
bin/magento mageforge:theme:list
# or alias
bin/magento frontend:list
```

--------------------------------

### Builder Array Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/types.md

Shows the format of a builder array, typically used in the constructor of `BuilderPool`. It contains instances of different builder implementations.

```php
// From BuilderPool constructor
$builders = [
    new HyvaThemes\Builder(...),
    new TailwindCSS\Builder(...),
    new MagentoStandard\Builder(...),
];
```

--------------------------------

### Build Theme from Code

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemePath.md

This pattern shows how to obtain a theme's filesystem path using ThemePath and then use a BuilderPool to get a specific builder for that theme to perform build operations.

```php
public function buildTheme(string $themeCode, BuilderPool $builderPool) {
    $themePath = new ThemePath($componentRegistrar);
    $path = $themePath->getPath($themeCode);
    
    if ($path === null) {
        throw new \\
```

--------------------------------

### List All Installed Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Retrieve a list of all themes installed in the Magento instance using the ThemeList service. This can be used to display available themes or for further processing.

```php
// List themes
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();
```

--------------------------------

### Conditional Theme Build Logic

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

This enhanced build method incorporates checks for vendor themes and Node.js setup before executing build steps. It allows themes to skip Node/Grunt steps if no setup is detected or if it's a vendor theme.

```php
public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    if (!$this->detect($themePath)) {
        return false;
    }

    // Check if this is a vendor theme (read-only, pre-built assets)
    if ($this->isVendorTheme($themePath)) {
        if ($isVerbose) {
            $io->note('Vendor theme detected. Skipping build steps (pre-built assets expected).');
        }
    } elseif ($this->hasNodeSetup()) {
        // Check if Node/Grunt setup exists
        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;
}
```

--------------------------------

### Restart DDEV

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Use these commands to restart DDEV if it is not starting correctly.

```bash
ddev poweroff
ddev start
```

--------------------------------

### Verify MageForge Installation

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Run a diagnostic command to check the status and configuration of the MageForge module within the Magento 2 installation. This helps ensure everything is set up correctly.

```bash
ddev magento mageforge:system:check
```

--------------------------------

### Integrate with Webpack Build Tool

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Integrates with Webpack by dynamically adjusting its configuration and running the build process. Ensure Webpack is installed in the project.

```php
public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Dynamically adjust Webpack configuration
    $webpackConfig = $themePath . '/webpack.config.js';
    if (file_exists($webpackConfig)) {
        // Adjust configuration if necessary
        // ...
    }

    // Run Webpack
    try {
        $this->shell->execute('cd ' . $themePath . ' && npx webpack --mode production');
    } catch (\Exception $e) {
        $io->error('Webpack build failed: ' . $e->getMessage());
        return false;
    }

    return true;
}
```

--------------------------------

### Theme Detection Strategies

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Implement the `detect()` method to uniquely identify your theme type. Examples include checking for specific configuration files, directory structures, or file content.

```php
public function detect(string $themePath): bool
{
    // Examples of detection strategies:

    // 1. Check for specific configuration files
    if (file_exists($themePath . '/your-config.json')) {
        return true;
    }

    // 2. Check for specific directory structures
    if (is_dir($themePath . '/your-special-folder')) {
        return true;
    }

    // 3. Check for content in specific files
    if (file_exists($themePath . '/theme.xml')) {
        $content = file_get_contents($themePath . '/theme.xml');
        if (strpos($content, 'your-identifier') !== false) {
            return true;
        }
    }

    return false;
}

```

--------------------------------

### Instantiate BuilderPool with Builders

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Create a new instance of BuilderPool by providing an array of builder implementations. This is typically done during dependency injection setup.

```php
$builders = [
    new HyvaThemes\Builder(...),
    new TailwindCSS\Builder(...),
    new MagentoStandard\Builder(...),
];

$pool = new BuilderPool($builders);
```

--------------------------------

### Implement Theme Build Process

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

This method performs the actual build process for a theme. It includes steps for SCSS/SASS compilation, JavaScript bundling, static content deployment, and cache clearing. Ensure necessary build tools are installed and configured.

```php
public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Build process examples:

    // 1. SCSS/SASS Compilation
    $io->text('Compiling SCSS files...');
    try {
        $this->shell->execute('sass ' . $themePath . '/web/scss:' . $themePath . '/web/css --style compressed');
    } catch (\Exception $e) {
        $io->error('SCSS compilation failed: ' . $e->getMessage());
        return false;
    }

    // 2. Create JavaScript bundles
    $io->text('Creating JavaScript bundles...');
    try {
        $this->shell->execute('webpack --config ' . $themePath . '/webpack.config.js');
    } catch (\Exception $e) {
        $io->error('JavaScript bundling failed: ' . $e->getMessage());
        return false;
    }

    // 3. Deploy static content
    $themeCode = basename($themePath);
    $this->staticContentDeployer->deploy($themeCode, $io, $output, $isVerbose);

    // 4. Clear cache
    $this->cacheCleaner->clean($io, $isVerbose);

    return true;
}
```

--------------------------------

### ThemeList

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/Services.md

Lists all installed themes in the system. It provides a method to retrieve all themes, returning an array of Theme objects containing their metadata.

```APIDOC
## ThemeList

### Description
Lists all installed themes in the system.

### Methods
- `getAllThemes()`

### Output
Array of Theme objects with metadata

### File
`src/Model/ThemeList.php`
```

--------------------------------

### Get and Build Theme with BuilderPool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Retrieve the appropriate theme builder using BuilderPool and then use it to build the theme. Ensure the builder is successfully obtained before proceeding with the build process.

```php
// Get the correct builder for a theme
$builder = $builderPool->getBuilder($themePath);

// Build the theme
if ($builder && $builder->build($themeCode, $themePath, $io, $output, $isVerbose)) {
    echo "Build successful!";
}
```

--------------------------------

### Theme Code Array Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/types.md

Illustrates the structure of a theme code array as returned by `ThemeList::getAllThemes()`. Each key is a theme code string, and the value is a `Theme` object.

```php
// From ThemeList::getAllThemes()
$themes = [
    'frontend/Magento/luma' => Theme{},
    'frontend/MyVendor/custom' => Theme{},
    'adminhtml/Magento/default' => Theme{},
];
```

--------------------------------

### CompatibilityChecker::check

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Checks all installed Magento modules for Hyvä theme compatibility, reporting on issues and summaries.

```APIDOC
## CompatibilityChecker::check

### Description
Checks all installed Magento modules for Hyvä theme compatibility, reporting on issues and summaries.

### Method
`check`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Signature
```php
public function check(
    SymfonyStyle $io,
    OutputInterface $output,
    bool $showAll = false,
    bool $thirdPartyOnly = false,
    bool $excludeVendor = true,
): array
```

### Parameters
- **io** (SymfonyStyle) - Required - Symfony console style for output
- **output** (OutputInterface) - Required - Console output interface
- **showAll** (bool) - Optional - Default: `false` - Show all modules including compatible ones
- **thirdPartyOnly** (bool) - Optional - Default: `false` - Exclude Magento_* core modules (requires excludeVendor=true)
- **excludeVendor** (bool) - Optional - Default: `true` - Exclude modules in vendor/ directory

### Return Type
`array`

### Response Example
```json
{
    "modules": {
        "ModuleName": {
            "compatible": true,
            "hasWarnings": false,
            "scanResult": { ... },
            "moduleInfo": { ... }
        }
    },
    "summary": {
        "total": 100,
        "compatible": 80,
        "incompatible": 20,
        "hyvaAware": 10,
        "criticalIssues": 15,
        "warningIssues": 5
    },
    "hasIncompatibilities": true
}
```
```

--------------------------------

### Hyvä Theme Detection Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Demonstrates how BuilderPool detects a Hyvä theme. It checks for the presence of specific Hyvä indicators like the 'web/tailwind' directory and 'hyva' in configuration files.

```php
$themePath = '/app/design/frontend/Vendor/hyva-luma';

// BuilderPool checks:
// 1. HyvaThemes::detect() looks for:
//    - /app/design/frontend/Vendor/hyva-luma/web/tailwind (EXISTS)
//    - 'hyva' in theme.xml or composer.json (TRUE)
//    → Returns true

$builder = $pool->getBuilder($themePath);
echo $builder->getName(); // "HyvaThemes"
```

--------------------------------

### SCSS Builder Implementation

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

Detects SCSS files and compiles them into CSS using the 'sass' command. Ensure the Sass compiler is installed and accessible.

```php
public function detect(string $themePath): bool
{
    return file_exists($themePath . '/web/scss/styles.scss');
}

public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    try {
        $this->shell->execute('sass ' . $themePath . '/web/scss:' . $themePath . '/web/css --style compressed');
        return true;
    } catch (\Exception $e) {
        $io->error('SCSS compilation failed: ' . $e->getMessage());
        return false;
    }
}
```

--------------------------------

### Get Detailed Module Issues

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Retrieves file-level details of compatibility issues for a specific module. Use this to diagnose problems within individual modules.

```php
public function getDetailedIssues(string $moduleName, array $moduleData): array
```

```php
$results = $checker->check($io, $output);

foreach ($results['modules'] as $moduleName => $moduleData) {
    if ($moduleData['compatible']) {
        continue;
    }
    
    $issues = $checker->getDetailedIssues($moduleName, $moduleData);
    
    foreach ($issues as $fileData) {
        echo "File: " . $fileData['file'];
        foreach ($fileData['issues'] as $issue) {
            echo "  Line {$issue['line']}: {$issue['description']}";
        }
    }
}
```

--------------------------------

### Custom TailwindCSS Theme Detection Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Illustrates the detection process for a custom TailwindCSS theme that is not a Hyvä theme. It shows how the BuilderPool prioritizes Hyvä detection and then falls back to general TailwindCSS detection.

```php
$themePath = '/app/design/frontend/Vendor/custom-theme';

// BuilderPool checks:
// 1. HyvaThemes::detect()
//    - /web/tailwind/web/tailwind (EXISTS)
//    - 'hyva' in theme.xml (FALSE)
//    → Returns false
//
// 2. TailwindCSS::detect()
//    - /web/tailwind (EXISTS)
//    - NOT a Hyvä theme
//    → Returns true

$builder = $pool->getBuilder($themePath);
echo $builder->getName(); // "TailwindCSS"
```

--------------------------------

### Apply Changes to Magento

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

After making code changes in the `/src/` directory, apply these updates to the Magento installation. This involves registering module updates and clearing the application cache.

```bash
ddev magento setup:upgrade
ddev magento cache:clean
```

--------------------------------

### Perform Mage-Forge System Diagnostics

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Run this command to gather comprehensive system information essential for troubleshooting and validating your Magento setup. It reports on PHP, Magento, database, Node.js, Composer, npm, Git, Xdebug, Redis, search engines, and disk space.

```bash
bin/magento mageforge:system:check
bin/magento system:check
```

--------------------------------

### Auto Repair Theme Dependencies with BuilderInterface

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Use the `autoRepair` method to ensure all necessary dependencies are present and correctly set up before building. This method handles tasks like installing Node modules and validating build tool configurations. It returns `false` if repairs fail.

```php
public function autoRepair(
    string $themePath,
    SymfonyStyle $io,
    OutputInterface $output,
    bool $isVerbose,
): bool
```

```php
$builder = $builderPool->getBuilder($themePath);
if (!$builder->autoRepair($themePath, $io, $output, true)) {
    echo "Failed to repair dependencies";
    return false;
}
```

--------------------------------

### Theme Watch Workflow Implementation

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Example of integrating BuilderPool into a theme watch workflow. It retrieves the builder for a given theme path and initiates the watch process, returning false if the theme type is not supported.

```php
public function watchTheme(string $themeCode, string $themePath) {
    $builder = $this->builderPool->getBuilder($themePath);
    
    if ($builder === null) {
        echo "Theme type not supported";
        return false;
    }
    
    // Watch mode runs indefinitely until user interrupts
    return $builder->watch($themeCode, $themePath, $this->io, $this->output, $isVerbose);
}
```

--------------------------------

### Theme Code String Array Example

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/types.md

Represents a flat array of theme code strings, as resolved by `AbstractCommand::resolveVendorThemes()`. This format is used for simpler lists of theme identifiers.

```php
// From AbstractCommand::resolveVendorThemes()
$themeCodes = [
    'Magento/luma',
    'MyVendor/custom',
    'MyVendor/checkout',
];
```

--------------------------------

### Implement Automatic Theme Repair

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/custom_theme_builders.md

This method automatically fixes potential issues before the build process begins. It handles creating missing configuration files and installing dependencies like Node modules. Ensure that npm is available in the environment.

```php
public function autoRepair(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool
{
    // Examples of repair measures:

    // 1. Create missing configuration files
    if (!file_exists($themePath . '/your-config.json')) {
        if ($isVerbose) {
            $io->warning('Configuration file missing. Creating default configuration...');
        }
        file_put_contents(
            $themePath . '/your-config.json',
            json_encode(['version' => '1.0.0', 'options' => []])
        );
    }

    // 2. Install missing dependencies
    if (!is_dir($themePath . '/node_modules')) {
        if ($isVerbose) {
            $io->warning('Node modules missing. Running npm install...');
        }
        try {
            $this->shell->execute('cd ' . $themePath . ' && npm install --quiet');
        } catch (\Exception $e) {
            $io->error('Error installing node modules: ' . $e->getMessage());
            return false;
        }
    }

    return true;
}
```

--------------------------------

### Get Detailed Hyvä Compatibility Issues

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Retrieve specific incompatibility details for a given module based on the compatibility check results. This provides granular information for resolving issues.

```php
// Get detailed issues
$issues = $checker->getDetailedIssues('ModuleName', $results['modules']['ModuleName']);
```

--------------------------------

### Display Mage-Forge and System Version

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Use this command to display the currently installed Mage-Forge version and check for the latest available release on GitHub. It also shows the core Magento system version.

```bash
bin/magento mageforge:system:version
bin/magento system:version
```

--------------------------------

### Instantiate ThemeCleaner

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeCleaner.md

Initializes the ThemeCleaner service with the necessary filesystem dependency.

```php
use OpenForgeProject\MageForge\Service\ThemeCleaner;
use Magento\Framework\Filesystem\Driver\File as Filesystem;

// Assuming $filesystem is an instance of Filesystem
$cleaner = new ThemeCleaner($filesystem);
```

--------------------------------

### Install MageForge via Composer

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Install the MageForge package using Composer. This is the primary method for adding MageForge to your Magento 2 project.

```bash
composer require openforgeproject/mageforge
```

--------------------------------

### Usage: Build All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Illustrates a pattern for building all themes by iterating through the theme list, resolving paths, selecting builders, and executing the build process. Handles cases where theme paths or builders are not found.

```php
public function buildAllThemes(
    ThemeList $themeList,
    ThemePath $themePath,
    BuilderPool $builderPool
) {
    $themes = $themeList->getAllThemes();
    $results = [];
    
    foreach ($themes as $theme) {
        $code = $theme->getCode();
        $path = $themePath->getPath($code);
        
        if ($path === null) {
            $results[$code] = "Theme path not found";
            continue;
        }
        
        $builder = $builderPool->getBuilder($path);
        if ($builder === null) {
            $results[$code] = "No builder available";
            continue;
        }
        
        $success = $builder->build($code, $path, $io, $output, false);
        $results[$code] = $success ? "Success" : "Failed";
    }
    
    return $results;
}

```

--------------------------------

### List Available Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Use this command to see all the theme types that MageForge supports and can build.

```bash
bin/magento mageforge:theme:list
```

--------------------------------

### Conventional Commits PR Title Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/CONTRIBUTING.md

Examples of correctly formatted PR titles using Conventional Commits for various types like feat, fix, docs, refactor, and perf. Ensure the type and description are present.

```markdown
✅ feat: add Hyvä compatibility check command
✅ fix: resolve npm installation issue
✅ docs: update README with new examples
✅ refactor: simplify theme builder logic
✅ perf: optimize static file cleaning

❌ Add new feature (missing type)
❌ Fixed bug (missing colon)
```

--------------------------------

### Build a Specific Theme

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Initiates the build process for a specified theme. Replace 'Magento/luma' with your target theme's identifier.

```bash
bin/magento mageforge:theme:build Magento/luma
```

--------------------------------

### NodePackageManager

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/Services.md

Manages Node.js packages, including installation, synchronization checks, and detection of outdated packages.

```APIDOC
## NodePackageManager

### Description
Manages Node.js packages (npm install, sync checks, outdated detection).

### Methods
- `installNodeModules()` — Install dependencies
- `isNodeModulesInSync()` — Check sync status
- `checkOutdatedPackages()` — List outdated packages

### File
`src/Service/NodePackageManager.php`
```

--------------------------------

### Build Selected Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Builds selected themes by compiling assets like CSS/TailwindCSS and deploying static content. Specify theme codes or use wildcards; an interactive prompt appears if none are provided.

```bash
bin/magento mageforge:theme:build <theme-code> [<theme-code> ...]
bin/magento frontend:build Magento/luma Magento/blank
```

--------------------------------

### CompatibilityChecker::__construct

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Initializes the CompatibilityChecker with necessary services for scanning modules and checking compatibility.

```APIDOC
## CompatibilityChecker::__construct

### Description
Initializes the CompatibilityChecker with necessary services for scanning modules and checking compatibility.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```php
public function __construct(
    ComponentRegistrarInterface $componentRegistrar,
    ModuleScanner $moduleScanner,
)
```

### Parameters
- **componentRegistrar** (ComponentRegistrarInterface) - Required - Magento component registrar for module paths
- **moduleScanner** (ModuleScanner) - Required - Module scanner service for detecting incompatibilities
```

--------------------------------

### getName()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Get the builder name used for registration and identification. This helps in distinguishing between different theme builder implementations.

```APIDOC
## getName()

### Description
Get the builder name used for registration and identification.

### Method
```php
public function getName(): string
```

### Return Type
`string`

Returns a unique name identifier for this builder.

### Available Builder Names:
- `HyvaThemes` - Hyva theme builder
- `TailwindCSS` - Custom TailwindCSS builder
- `MagentoStandard` - Standard Magento theme builder

### Example
```php
$builder = $builderPool->getBuilder($themePath);
echo "Using builder: " . $builder->getName();
// Output: "Using builder: HyvaThemes"
```
```

--------------------------------

### Automatic Builder Selection and Build

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Retrieves the appropriate theme builder based on the theme path and initiates the build process. This is the recommended way to build themes.

```php
// Get the correct builder automatically
$builder = $builderPool->getBuilder($themePath);
if ($builder) {
    $builder->build($themeCode, $themePath, $io, $output, true);
}
```

--------------------------------

### Get Inspector Enabled Status

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/configuration.md

Retrieves the global enabled status of the Frontend Inspector. This is useful for conditionally enabling or disabling the feature.

```php
// Get inspector enabled status
$config = $objectManager->get(\\Magento\\Framework\\App\\Config\\ScopeConfigInterface::class);
$isEnabled = $config->isSetFlag(
    'dev/mageforge_inspector/enabled',
    \\Magento\\Store\\Model\\ScopeInterface::SCOPE_STORE
);
```

--------------------------------

### Creating a Builder Instance by Type

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderFactory.md

Shows how to retrieve a specific theme builder instance from the factory using its registered type name. Handles potential exceptions if the builder is not found.

```php
try {
    $builder = $factory->create('HyvaThemes');
    // Use $builder...
} catch (\InvalidArgumentException $e) {
    echo "Builder not found: " . $e->getMessage();
}
```

--------------------------------

### Registering Theme Builders with BuilderFactory

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderFactory.md

Demonstrates how to register different theme builder implementations with the BuilderFactory. This is usually done via dependency injection in `di.xml`.

```php
$factory = new BuilderFactory();
$factory->addBuilder(new HyvaThemes\Builder(...));
$factory->addBuilder(new TailwindCSS\Builder(...));
$factory->addBuilder(new MagentoStandard\Builder(...));
```

--------------------------------

### Get All Registered Builders

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderPool.md

Retrieve an array containing all the builder instances currently registered with the BuilderPool. This can be useful for introspection or iterating through available builders.

```php
$builders = $pool->getBuilders();
foreach ($builders as $builder) {
    echo "Available builder: " . $builder->getName();
}
```

--------------------------------

### build()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Build the theme assets, including static content deployment and cache cleaning. This method orchestrates the entire theme building process.

```APIDOC
## build()

### Description
Build the theme assets, including static content deployment and cache cleaning.

### Method
```php
public function build(
    string $themeCode,
    string $themePath,
    SymfonyStyle $io,
    OutputInterface $output,
    bool $isVerbose,
): bool
```

### Parameters
#### Path Parameters
- **themeCode** (string) - Yes - Theme code (e.g., "Magento/luma")
- **themePath** (string) - Yes - Absolute path to the theme directory
- **io** (SymfonyStyle) - Yes - Symfony console style for formatted output
- **output** (OutputInterface) - Yes - Console output interface
- **isVerbose** (bool) - Yes - Flag to show verbose output

### Return Type
`bool`

Returns `true` if build succeeded, `false` on error.

### Typical Build Flow:
1. Clean static content (developer mode only)
2. Validate and repair dependencies via `autoRepair()`
3. Clean symlinks
4. Run builder-specific build process
5. Deploy static content
6. Clean cache

### Example
```php
$builder = $builderPool->getBuilder($themePath);
if ($builder && $builder->build('MyVendor/mytheme', $themePath, $io, $output, true)) {
    echo "Build successful!";
}
```
```

--------------------------------

### Constructor for ThemeList

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Initializes the ThemeList service by injecting Magento's native theme list.

```php
public function __construct(
    MagentoThemeList $magentoThemeList,
)
```

--------------------------------

### Instantiate ThemePath

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemePath.md

Instantiate the ThemePath class by passing the ComponentRegistrarInterface. This is the first step before using its methods.

```php
public function __construct(
    ComponentRegistrarInterface $componentRegistrar,
)
```

```php
$themePath = new ThemePath($componentRegistrar);
```

--------------------------------

### Theme Building Workflow

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/Services.md

This sequence outlines the steps involved in building a theme using MageForge services. It covers obtaining theme information, selecting a builder, performing pre-build and build operations, and cleaning the cache.

```plaintext
1. Get theme info: ThemePath::getPath() / ThemeList::getAllThemes()
2. Select builder: BuilderPool::getBuilder()
3. Pre-build: BuilderInterface::autoRepair()
4. Build: BuilderInterface::build()
5. Post-build: CacheCleaner::clean()
```

--------------------------------

### BuilderPool

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/Services.md

Automatically selects the correct builder for a theme based on detection mechanisms. It provides methods to get a specific builder or a list of available builders.

```APIDOC
## BuilderPool

### Description
Automatically selects the correct builder for a theme based on detection.

### Methods
- `getBuilder()`
- `getBuilders()`

### File
`src/Service/ThemeBuilder/BuilderPool.php`
```

--------------------------------

### List All Themes

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Retrieves and iterates through all available themes. Ensure ThemeList and Magento theme data are properly initialized.

```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

foreach ($themes as $theme) {
    echo $theme->getCode() . ": " . $theme->getThemeTitle();
}
```

--------------------------------

### Install Mageforge Module via Composer

Source: https://github.com/openforgeproject/mageforge/wiki/Development

Use these Composer commands to add the Mageforge repository, require the module, and enable it in your Magento 2 project.

```bash
# add repository
composer config repositories.mageforge vcs https://github.com/OpenForgeProject/mageforge.git

# require module
composer require openforgeproject/mageforge:dev-main --prefer-source

# enable module
bin/magento setup:upgrade
```

--------------------------------

### Clean Theme Files (Dry Run)

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Performs a dry run to preview theme files that would be cleaned from public static and view preprocessed directories. Set the final boolean to false for actual cleaning.

```php
$cleaner = new ThemeCleaner($filesystem);

// Preview what would be cleaned
$cleaner->cleanPubStatic('MyVendor/custom', $io, true, true);
$cleaner->cleanViewPreprocessed('MyVendor/custom', $io, true, true);

// Actual clean
$cleaner->cleanPubStatic('MyVendor/custom', $io, false, true);
```

--------------------------------

### CompatibilityChecker Constructor

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Initializes the CompatibilityChecker with necessary services for module scanning and registration.

```php
public function __construct(
    ComponentRegistrarInterface $componentRegistrar,
    ModuleScanner $moduleScanner
)
```

--------------------------------

### getAllThemes()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Retrieves all installed themes in the Magento system. It returns a keyed array where the key is the theme path and the value is a Theme object containing theme metadata.

```APIDOC
## getAllThemes()

### Description
Get all installed themes in the system.

### Method
public

### Endpoint
N/A (Method within a class)

### Parameters
None

### Return Type
`array<string, Theme>`

Returns a keyed array of Theme objects where:
- **Key:** Theme path (e.g., "frontend/Magento/luma")
- **Value:** Magento\Theme\Model\Theme object

### Theme Object Properties:
- `getCode()` - Returns theme code (e.g., "Magento/luma")
- `getThemeTitle()` - Returns human-readable theme title
- `getId()` - Returns Magento theme ID
- `getParentId()` - Returns parent theme ID if applicable

### Request Example
```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

foreach ($themes as $path => $theme) {
    echo "Path: $path\n";
    echo "Code: " . $theme->getCode() . "\n";
    echo "Title: " . $theme->getThemeTitle() . "\n";
    echo "---\n";
}
```

### Response Example
```json
{
  "frontend/Magento/luma": {
    "code": "Magento/luma",
    "title": "Magento Luma",
    "id": 1,
    "parentId": null
  },
  "frontend/MyVendor/custom": {
    "code": "MyVendor/custom",
    "title": "My Custom Theme",
    "id": 2,
    "parentId": 1
  }
}
```
```

--------------------------------

### Check Modules for Hyvä Compatibility

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Scans all modules for Hyvä compatibility issues, with options to control output and filtering. Use this to get a comprehensive overview of module compatibility.

```php
public function check(
    SymfonyStyle $io,
    OutputInterface $output,
    bool $showAll = false,
    bool $thirdPartyOnly = false,
    bool $excludeVendor = true
): array
```

```php
$checker = new CompatibilityChecker($componentRegistrar, $moduleScanner);

// Check all modules
$results = $checker->check($io, $output, false, false, true);

echo "Total modules: " . $results['summary']['total'];
echo "Compatible: " . $results['summary']['compatible'];
echo "Incompatible: " . $results['summary']['incompatible'];
echo "Critical issues: " . $results['summary']['criticalIssues'];
```

--------------------------------

### Upgrade and Clean Cache

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Use this command to resolve module not found errors after making changes.

```bash
ddev magento setup:upgrade && ddev magento cache:clean
```

--------------------------------

### detect()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Detect whether the builder can handle a theme at the given path. This method is crucial for selecting the appropriate builder for a specific theme.

```APIDOC
## detect()

### Description
Detect whether the builder can handle a theme at the given path.

### Method
```php
public function detect(string $themePath): bool
```

### Parameters
#### Path Parameters
- **themePath** (string) - Yes - Absolute path to the theme directory

### Return Type
`bool`

Returns `true` if the builder can handle this theme, `false` otherwise.

### Example
```php
$builder = new HyvaThemes\Builder(...);
if ($builder->detect('/path/to/app/design/frontend/MyVendor/mytheme')) {
    echo "This is a Hyva theme";
}
```
```

--------------------------------

### Conventional Commits for Direct Commits

Source: https://github.com/openforgeproject/mageforge/blob/main/CONTRIBUTING.md

Examples of using Conventional Commits format for direct commits to the main branch, including feature, hotfix, documentation, and chore types.

```bash
# Feature example
git commit -m "feat: add new command for theme token generation"

# Hotfix example
git commit -m "fix: resolve critical security vulnerability in npm dependencies"

# Documentation update
git commit -m "docs: add troubleshooting section to releases.md"

# Chore example
git commit -m "chore: update GitHub Actions to latest versions"
```

--------------------------------

### Conventional Commits Breaking Change Examples

Source: https://github.com/openforgeproject/mageforge/blob/main/CONTRIBUTING.md

Demonstrates how to indicate breaking changes in Conventional Commits by adding an exclamation mark after the type, which signals a major version bump.

```markdown
feat!: remove legacy theme builder API
fix!: change command argument order
```

--------------------------------

### Include All Modules (Including Vendor)

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/CompatibilityChecker.md

Performs a comprehensive scan including all modules, both core and third-party, as well as those in the vendor directory. Reports the total number of modules scanned.

```php
// Include everything
$results = $checker->check(
    $io,
    $output,
    showAll: true,
    thirdPartyOnly: false,
    excludeVendor: false
);

echo "Total modules scanned: " . $results['summary']['total'];
```

--------------------------------

### Check Hyvä Compatibility and Display Results

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Scan installed modules for Hyvä compatibility issues and format the results for display. This helps identify potential conflicts or configuration problems.

```php
// Check modules
$checker = new CompatibilityChecker($componentRegistrar, $moduleScanner);
$results = $checker->check($io, $output);

// Display results
$tableData = $checker->formatResultsForDisplay($results);
$io->table(['Module', 'Status', 'Issues'], $tableData);
```

--------------------------------

### Clone MageForge Repository

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/development.md

Clone the MageForge repository and navigate into the project directory. This is the first step to setting up your local development environment.

```bash
git clone git@github.com:OpenForgeProject/mageforge.git
cd mageforge
```

--------------------------------

### Build Theme Assets with BuilderInterface

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

The `build` method is responsible for compiling theme assets, deploying static content, and cleaning caches. It requires theme details, console I/O objects, and a verbosity flag. Ensure the builder is correctly obtained before calling this method.

```php
public function build(
    string $themeCode,
    string $themePath,
    SymfonyStyle $io,
    OutputInterface $output,
    bool $isVerbose,
): bool
```

```php
$builder = $builderPool->getBuilder($themePath);
if ($builder && $builder->build('MyVendor/mytheme', $themePath, $io, $output, true)) {
    echo "Build successful!";
}
```

--------------------------------

### Get Filesystem Path for a Theme

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemePath.md

Retrieve the absolute filesystem path for a given theme code. The theme code must be in the format 'Vendor/theme' and is case-sensitive. Returns null if the theme is not registered.

```php
public function getPath(string $themeCode): ?string
```

```php
$themePath = new ThemePath($componentRegistrar);

// Frontend theme
$path = $themePath->getPath('Magento/luma');
// Output: "/app/design/frontend/Magento/luma"

// Adminhtml theme
$path = $themePath->getPath('Magento/adminhtml');
// Output: "/app/design/adminhtml/Magento/default"

// Non-existent theme
$path = $themePath->getPath('NonExistent/theme');
// Output: null
```

--------------------------------

### Build Specific Theme

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/README.md

Builds a specific theme by obtaining its path and using a theme builder. Requires ComponentRegistrar, IO, and output interfaces.

```php
$themePath = new ThemePath($componentRegistrar);
$path = $themePath->getPath('MyVendor/custom');

$builder = $builderPool->getBuilder($path);
$success = $builder->build('MyVendor/custom', $path, $io, $output, true);
```

--------------------------------

### Validate Theme Code Existence

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemePath.md

Check if a theme code corresponds to an installed theme by attempting to retrieve its path. This is useful for validating user input or ensuring a theme exists before proceeding.

```php
$themePath = new ThemePath($componentRegistrar);
$themeCode = "MyVendor/mytheme";

$path = $themePath->getPath($themeCode);
if ($path === null) {
    echo "Theme '$themeCode' is not installed";
    return false;
}

echo "Theme path: $path";
```

--------------------------------

### watch()

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/BuilderInterface.md

Runs the theme watch process for continuous file monitoring and automatic rebuilds. This method monitors theme files for changes, automatically rebuilds assets, and cleans static content if in developer mode. It continues indefinitely until the user interrupts the process (e.g., with Ctrl+C).

```APIDOC
## watch()

### Description
Runs the theme watch process for continuous file monitoring and automatic rebuilds. Monitors theme files for changes, automatically rebuilds assets, and cleans static content if in developer mode. Continues indefinitely until user interrupts (Ctrl+C).

### Method
`watch`

### Parameters
#### Path Parameters
- **themeCode** (string) - Required - Theme code (e.g., "Magento/luma")
- **themePath** (string) - Required - Absolute path to the theme directory
- **io** (SymfonyStyle) - Required - Symfony console style for output
- **output** (OutputInterface) - Required - Console output interface
- **isVerbose** (bool) - Required - Flag to show verbose output

### Return Type
`bool`

Returns `true` when watch mode exits successfully, `false` on error.

### Example
```php
$builder = $builderPool->getBuilder($themePath);
// This will run indefinitely until Ctrl+C
$builder->watch('MyVendor/mytheme', $themePath, $io, $output, false);
```
```

--------------------------------

### Usage: Vendor/Theme Filtering

Source: https://github.com/openforgeproject/mageforge/blob/main/_autodocs/api-reference/ThemeList.md

Shows how to filter the list of all themes based on the theme code. Examples include filtering by a specific vendor, filtering for Magento core themes, and filtering for custom themes.

```php
$themeList = new ThemeList($magentoThemeList);
$themes = $themeList->getAllThemes();

// Filter by vendor
$vendor = "MyVendor";
$vendorThemes = array_filter(
    $themes,
    fn($theme) => str_starts_with($theme->getCode(), $vendor . "/")
);

// Filter Magento core themes
$magentoCoreThemes = array_filter(
    $themes,
    fn($theme) => str_starts_with($theme->getCode(), "Magento/")
);

// Filter custom themes (exclude Magento)
$customThemes = array_filter(
    $themes,
    fn($theme) => !str_starts_with($theme->getCode(), "Magento/")
);

```

--------------------------------

### Clean Theme Static Files and Cache

Source: https://github.com/openforgeproject/mageforge/blob/main/docs/commands_reference.md

Cleans theme static files and cache directories. Use the --all option to clean all themes or --dry-run to preview changes without deleting.

```bash
bin/magento mageforge:theme:clean [<theme-code> ...]
bin/magento mageforge:theme:clean --all
bin/magento mageforge:theme:clean --dry-run
```

--------------------------------

### Watch for Theme Changes

Source: https://github.com/openforgeproject/mageforge/blob/main/README.md

Enables development mode, automatically rebuilding the theme when source files change. Useful for live development.

```bash
bin/magento mageforge:theme:watch Magento/luma
```