commands.md

MageForge Commands Documentation

This document provides a comprehensive overview of all commands available in the MageForge module. It's designed to help developers understand the structure and functionality of each command.

Command Architecture

All commands in MageForge follow a consistent structure based on Symfony's Console Component. They extend the Symfony\Component\Console\Command\Command class and implement:

• A constructor that injects dependencies
• A configure() method that sets the command name, description, and arguments/options
• An execute() method that handles the command logic

Available Commands

1. ListThemeCommand (mageforge:theme:list)

Purpose: Lists all available Magento themes in the installation.

File: /src/Console/Command/ListThemeCommand.php

Dependencies:

• ThemeList - Service to retrieve theme information

Usage:

bin/magento mageforge:theme:list

Implementation Details:

• Retrieves all themes from the ThemeList service
• Displays a formatted table with theme information (code, title, path)
• Returns success status code

---

2. BuildThemeCommand (mageforge:theme:build)

Purpose: Builds specified Magento themes by compiling assets and deploying static content.

File: /src/Console/Command/BuildThemeCommand.php

Dependencies:

• ThemePath - Service to resolve theme paths
• ThemeList - Service to retrieve theme information
• BuilderPool - Service to get appropriate builders for themes

Usage:

bin/magento mageforge:theme:build [<themeCodes>...]

Aliases:

• frontend:build

Implementation Details:

• themeCodes accepts single themes (Vendor/theme) or just the vendor name (Vendor) to target all themes of a specific vendor.
• If no theme codes are provided, displays an interactive prompt to select themes
• For each selected theme:
  1. Resolves the theme path
  2. Determines the appropriate builder for the theme type
  3. Executes the build process
• Displays a summary of built themes and execution time

---

3. ThemeWatchCommand (mageforge:theme:watch)

Purpose: Watches theme files for changes and automatically rebuilds when changes are detected.

File: /src/Console/Command/ThemeWatchCommand.php

Dependencies:

• BuilderPool - Service to get appropriate builders for themes
• ThemeList - Service to retrieve theme information
• ThemePath - Service to resolve theme paths

Usage:

bin/magento mageforge:theme:watch [--theme=THEME]

Aliases:

• frontend:watch

Options:

• --theme=THEME - Theme code in format Vendor/theme to watch

Implementation Details:

• If no theme code is provided, displays an interactive prompt to select a theme
• Resolves the theme path
• Determines the appropriate builder for the theme type
• Starts a watch process that monitors for file changes

---

4. CleanCommand (mageforge:theme:clean)

Purpose: Cleans var/view_preprocessed, pub/static, var/page_cache, var/tmp and generated directories for specific theme.

File: /src/Console/Command/Theme/CleanCommand.php

Dependencies:

• Filesystem - Magento filesystem component for file operations
• ThemeList - Service to retrieve theme information
• ThemePath - Service to resolve theme paths

Usage:

bin/magento mageforge:theme:clean [<themename>...]

Implementation Details:

• Can accept multiple themes like Vendor/theme1 Vendor/theme2.
• Accepts simply the vendor name Vendor to clean all registered themes for a vendor.
• If no theme name is provided:
  • In interactive terminals, displays an interactive prompt to select the theme to clean
  • In non-interactive environments, prints the list of available themes and exits, requiring an explicit theme name
• Validates that the specified theme exists
• Cleans the following directories for the theme:
  • var/view_preprocessed/css/frontend/Vendor/theme
  • var/view_preprocessed/source/frontend/Vendor/theme
  • pub/static/frontend/Vendor/theme
• Additionally cleans these global directories:
  • var/page_cache/*
  • var/tmp/*
  • generated/*
• Displays a summary of cleaned directories
• Returns success status code

---

5. SystemCheckCommand (mageforge:system:check)

Purpose: Displays system information relevant to Magento development.

File: /src/Console/Command/SystemCheckCommand.php

Dependencies:

• ProductMetadataInterface - For retrieving Magento version
• Escaper - For HTML escaping output

Usage:

bin/magento mageforge:system:check

Implementation Details:

• Retrieves and displays:
  • PHP version
  • Node.js version (with comparison to latest LTS)
  • MySQL version
  • Operating System information
  • Magento version
• Utilizes Symfony's table component for formatted output

---

6. VersionCommand (mageforge:version)

Purpose: Displays the current and latest version of the MageForge module.

File: /src/Console/Command/VersionCommand.php

Dependencies:

• File - Filesystem driver for reading files

Usage:

bin/magento mageforge:version

Implementation Details:

• Reads the current module version from composer.lock
• Fetches the latest version from GitHub API
• Displays both versions for comparison

Note: This command requires a composer.lock file to be present in the Magento root directory. If composer.lock is absent (e.g., gitignored or not yet generated), the current version cannot be determined.

---

7. CompatibilityCheckCommand (mageforge:hyva:compatibility:check)

Purpose: Scans all Magento modules for Hyvä theme compatibility issues such as RequireJS, Knockout.js, jQuery, and UI Components usage.

File: /src/Console/Command/Hyva/CompatibilityCheckCommand.php

Dependencies:

• CompatibilityChecker - Main orchestrator service for scanning modules

Usage:

bin/magento mageforge:hyva:compatibility:check [options]

Aliases:

• m:h:c:c
• hyva:check

Options:

• --show-all / -a - Show all modules including compatible ones
• --include-vendor - Include Magento core modules in scan (default: third-party only)
• --detailed / -d - Show detailed file-level issues for incompatible modules

Interactive Mode: When running without any options, the command launches an interactive menu (using Laravel Prompts):

# Launch interactive menu
bin/magento m:h:c:c

The menu allows you to select:

• ☐ Show all modules including compatible ones
• ☐ Show only incompatible modules (default behavior)
• ☐ Include Magento core modules (default: third-party only)
• ☐ Show detailed file-level issues with line numbers

Use Space to toggle options, Enter to confirm and start the scan.

Default Behavior: Without any flags, the command scans third-party modules only (excludes Magento_* modules but includes vendor third-party like Hyva, PayPal, Mollie, etc.).

Examples:

# Basic scan (third-party modules only - DEFAULT)
bin/magento m:h:c:c

# Include Magento core modules
bin/magento m:h:c:c --include-vendor

# Show all modules including compatible ones
bin/magento m:h:c:c -a

# Show detailed file-level issues
bin/magento m:h:c:c -d

# Using full command name
bin/magento mageforge:hyva:compatibility:check --detailed

Implementation Details:

• Scans module directories for JS, XML, and PHTML files
• Detects incompatibility patterns:
  • Critical Issues:
    • RequireJS define() and require() usage
    • Knockout.js observables and computed properties
    • Magento UI Components in XML
    • data-mage-init and x-magento-init in templates
  • Warnings:
    • jQuery AJAX direct usage
    • jQuery DOM manipulation
    • Block removal in layout XML (review needed)
• Displays results in formatted tables with color-coded status:
  • ✓ Green: Compatible modules
  • ⚠ Yellow: Warnings (non-critical issues)
  • ✗ Red: Incompatible (critical issues)
  • ✓ Hyvä-Aware: Modules with Hyvä compatibility packages
• Provides summary statistics:
  • Total modules scanned
  • Compatible vs. incompatible count
  • Hyvä-aware modules count
  • Critical issues and warnings count
• Shows detailed file paths and line numbers with --detailed flag
• Provides helpful recommendations for resolving issues
• Returns exit code 1 if any critical issues are found. If only warnings (and no critical issues) are detected, the command returns exit code 0 so CI/CD pipelines do not fail on warnings alone.

Detected Patterns:

JavaScript Files (.js):

• define([ - RequireJS module definition
• require([ - RequireJS dependency loading
• ko.observable / ko.observableArray / ko.computed - Knockout.js
• $.ajax / jQuery.ajax - jQuery AJAX
• mage/ - Magento RequireJS module references

XML Files (.xml):

• <uiComponent - UI Component declarations
• component="uiComponent" - UI Component references
• component="Magento_Ui/js/ - Magento UI JS components
• <referenceBlock.*remove="true" - Block removals

PHTML Files (.phtml):

• data-mage-init= - Magento JavaScript initialization
• x-magento-init - Magento 2.4+ JavaScript initialization
• $(.*). - jQuery DOM manipulation patterns
• require([ - RequireJS in templates

Recommendations Provided:

• Check for Hyvä compatibility packages on hyva.io/compatibility
• Review module vendor documentation for Hyvä support
• Consider refactoring RequireJS/Knockout to Alpine.js
• Contact module vendors for Hyvä-compatible versions

---

8. TokensCommand (mageforge:hyva:tokens)

Purpose: Generates Hyvä design tokens from design.tokens.json or hyva.config.json configuration files.

File: /src/Console/Command/Theme/TokensCommand.php

Dependencies:

• ThemeList - Service to retrieve theme information
• ThemePath - Service to resolve theme paths
• BuilderPool - Service to verify Hyvä theme type
• File - Filesystem driver for directory checks
• Shell - Shell command executor

Usage:

bin/magento mageforge:hyva:tokens [<themeCode>]

Aliases:

• m:h:t

Arguments:

• themeCode (optional) - Theme code in format Vendor/theme

Examples:

# Interactive mode - select theme from list
bin/magento m:h:t

# Direct execution
bin/magento mageforge:hyva:tokens Hyva/default

Implementation Details:

• If no theme code is provided, displays an interactive prompt to select a Hyvä theme
• Validates that the theme is installed and is a Hyvä theme
• Checks if the theme has been built (node_modules exists)
• Changes to the theme's web/tailwind directory
• Executes npx hyva-tokens to generate design tokens
• For themes in app/design/frontend/:
  • Generates tokens in web/tailwind/generated/hyva-tokens.css
• For vendor themes (in vendor/ directory):
  • Generates tokens in web/tailwind/generated/hyva-tokens.css first
  • Copies the generated file to var/generated/hyva-token/{ThemeCode}/hyva-tokens.css
  • Displays a note informing that tokens were saved to var/generated location
• Returns success status code or error message

Requirements:

• Theme must be a Hyvä theme
• Theme must be built first (mageforge:theme:build)
• Node.js and npm must be available
• hyva-tokens package must be installed (via theme build)

Output Locations:

• Custom themes (app/design): {theme-path}/web/tailwind/generated/hyva-tokens.css
• Vendor themes (vendor/): var/generated/hyva-token/{ThemeCode}/hyva-tokens.css

Error Handling:

• Returns error if theme is not installed
• Returns error if theme is not a Hyvä theme
• Returns warning if node_modules not found (build required)
• Returns error if tailwind directory doesn't exist

---

9. InspectorCommand (mageforge:theme:inspector)

Purpose: Enable, disable, or check status of the MageForge Frontend Inspector - an interactive element inspector for debugging templates, blocks, and modules in the frontend.

File: /src/Console/Command/Dev/InspectorCommand.php

Dependencies:

• WriterInterface - Service to write configuration values
• State - Service to check Magento application mode
• CacheManager - Service to clean configuration cache

Usage:

# Enable inspector
bin/magento mageforge:theme:inspector enable

# Disable inspector
bin/magento mageforge:theme:inspector disable

# Check status
bin/magento mageforge:theme:inspector status

Implementation Details:

• Enable Action:
  • Validates that Magento is in developer mode
  • Sets dev/mageforge_inspector/enabled configuration to 1
  • Cleans config cache
  • Displays usage instructions with keyboard shortcuts
• Disable Action:
  • Validates that Magento is in developer mode
  • Sets dev/mageforge_inspector/enabled configuration to 0
  • Cleans config cache
• Status Action:
  • Displays current Magento mode (developer/production/default)
  • Shows inspector enabled/disabled status
  • Provides guidance if requirements are not met

Requirements:

• Developer Mode: Inspector can only be enabled/disabled in developer mode
• Allowed IP: Inspector only renders for IPs configured in Magento's Developer Client Restrictions
• Browser: Modern browser with JavaScript enabled (Alpine.js support)

Frontend Usage (after enabling):

• Press Ctrl+Shift+I (or Cmd+Option+I on macOS) to toggle the inspector
• Hover over elements to see their template information in real-time
• Click on an element to pin the inspector panel
• Press ESC to close the inspector
• Use copy buttons to copy template paths and block class names to clipboard

Security:

• Only active in developer mode
• Respects Magento's Developer Client Restrictions (allowed IPs)
• Automatically disabled in production mode
• Data attributes only injected when all security checks pass

Error Handling:

• Returns error with instructions if not in developer mode
• Clears error message explaining current mode and how to switch
• Validates action argument (must be: enable, disable, or status)

---

Command Services

The commands rely on several services for their functionality:

Hyvä Services

• CompatibilityChecker: Main orchestrator for Hyvä compatibility scanning
• ModuleScanner: Recursively scans module directories for relevant files
• IncompatibilityDetector: Pattern matching service for detecting incompatibilities

Builder Services

• 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

• ThemeList: Retrieves all installed themes
• ThemePath: Resolves theme codes to filesystem paths
• StaticContentDeployer: Handles static content deployment
• CacheCleaner: Manages cache cleaning after theme builds

Utility Services

• DependencyChecker: Verifies required dependencies for theme building
• GruntTaskRunner: Executes Grunt tasks for theme compilation

Command Execution Flow

1. The command is executed via the Magento CLI framework
2. Dependencies are injected via constructor
3. Arguments and options are processed
4. Interactive prompts are shown if required
5. The appropriate services are called to perform the command's task
6. Formatted output is displayed to the user
7. A status code is returned (success or failure)

Error Handling

All commands implement error handling via try-catch blocks and return appropriate error messages and status codes when failures occur. Interactive commands also provide suggestions for resolving issues.