From 949220e73d98d8e7765daa84f286aee3347ea7ce Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:00:17 +0200 Subject: [PATCH 1/6] feat: update README and commands documentation --- README.md | 181 +++++------- docs/advanced_usage.md | 149 ---------- docs/commands.md | 516 ---------------------------------- docs/commands_reference.md | 205 ++++++++++++++ docs/custom_theme_builders.md | 6 +- 5 files changed, 278 insertions(+), 779 deletions(-) delete mode 100644 docs/advanced_usage.md delete mode 100644 docs/commands.md create mode 100644 docs/commands_reference.md diff --git a/README.md b/README.md index 22440bdc..c445e6bc 100644 --- a/README.md +++ b/README.md @@ -4,167 +4,118 @@ [![Release](https://img.shields.io/github/v/release/OpenForgeProject/mageforge)](https://github.com/OpenForgeProject/mageforge/releases) [![License](https://img.shields.io/badge/license-GPL--3.0-blue)](LICENSE) -MageForge is a powerful CLI front-end development toolkit for Magento 2 that simplifies theme development workflows. It provides tools for many types of Magento themes and can be easily extended for custom themes. +MageForge is a powerful CLI toolkit for Magento 2 front-end development. It simplifies theme building workflows, supports multiple theme types (Magento Standard, Hyvä, TailwindCSS, custom), and includes developer tools like the Frontend Inspector. ## Table of Contents -- [Supported Magento Versions](#supported-magento-versions) -- [Features](#features) - - [Supported Theme-Types](#supported-theme-types-) - - [Available Commands](#available-commands) -- [Getting Started](#getting-started) - - [Installation](#installation) - - [Quick Start Guide](#quick-start-guide) - - [Frontend Inspector](#frontend-inspector-️) -- [Additional Documentation](#additional-documentation) +- [Requirements](#requirements) +- [Supported Theme Types](#supported-theme-types-) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Frontend Inspector](#frontend-inspector-) +- [Commands Reference](#commands-reference) +- [Documentation](#documentation) - [Support](#support) -- [Project Information](#project-information) - [Credits](#credits) -> **Contributor?** Jump straight to the [Development Guide](./docs/development.md) for DDEV setup, workflow, and coding standards. +> **Contributor?** Jump to the [Development Guide](./docs/development.md). -## Supported Magento Versions +## Requirements -MageForge requires Magento 2.4.7 or higher with PHP 8.3 or higher. -Please ensure that your Magento installation meets this requirement before installation. +- Magento 2.4.7+ (tested on 2.4.7-p10, 2.4.8-p5, 2.4.9) +- PHP 8.3+ +- Node.js (LTS recommended) +- Composer -## Features - -### Supported Theme-Types 🎨 - -![Mageforge Hero](./.github/assets/cli-chooser.png) +## Supported Theme Types 🎨 | Theme Type | Support Status | | ------------------------------- | ---------------------------------------------------------- | | 🎯 Magento Standard | ✅ Fully Supported | | 🚀 Hyvä (TailwindCSS 3.x / 4.x) | ✅ Fully Supported | +| 🛒 Hyvä Checkout | ✅ Fully Supported | 🔄 Hyvä Fallback | ✅ Fully Supported | | 🎨 Custom TailwindCSS (no Hyvä) | ✅ Fully Supported | | 💼 Avanta B2B | ✅ Fully Supported | -| 🥰 Your Custom Theme (`css`, `sass`, `less`, ... ) | [Create your own Builder](./docs/custom_theme_builders.md) | - ---- - -### Available Commands - -| Command | Description | Aliases | -| ----------------------------------- | --------------------------------------------------------- | ------------------------- | -| `mageforge:theme:list` | Lists all available themes | `frontend:list` | -| `mageforge:theme:build` | Builds selected themes (CSS/TailwindCSS) | `frontend:build` | -| `mageforge:theme:watch` | Starts watch mode for theme development | `frontend:watch` | -| `mageforge:theme:clean` | Clean theme static files and cache directories | `frontend:clean` | -| `mageforge:theme:inspector` | Enable, disable or check status of Frontend Inspector | - | -| `mageforge:hyva:compatibility:check`| Check modules for Hyvä theme compatibility issues | `hyva:check` | -| `mageforge:hyva:tokens` | Generate Hyvä design tokens (Hyvä themes only) | `hyva:tokens` | -| `mageforge:system:version` | Shows current and latest version of the module | `system:version` | -| `mageforge:system:check` | Get system information (OS, PHP, Database, Node.js, etc.) | `system:check` | - -## Frontend Toolbar with Inspector and Performance Metrics -![Mageforge Toolbar](./.github/assets/toolbar.jpeg) +| 🥰 Your Custom Theme | [Create your own Builder](./docs/custom_theme_builders.md) | -## Getting Started +## Installation -### Installation - -1. Install the module via Composer: +1. Install via Composer: ```bash composer require openforgeproject/mageforge ``` 2. Enable the module: + ```bash bin/magento module:enable OpenForgeProject_MageForge bin/magento setup:upgrade ``` -### Quick Start Guide - -1. List available themes: - - ```bash - bin/magento mageforge:theme:list - ``` - -2. Build a theme: - - ```bash - bin/magento mageforge:theme:build - ``` - - Example: `bin/magento mageforge:theme:build Magento/luma` - -3. Start development watch mode: - - ```bash - bin/magento mageforge:theme:watch - ``` - -4. Generate Hyvä design tokens (for Hyvä themes): - - ```bash - bin/magento mageforge:hyva:tokens - ``` - - This creates a `generated/hyva-tokens.css` file from your design tokens configuration. - -5. Enjoy automatic CSS rebuilding as you work on your theme files! +## Quick Start ---- +```bash +# 1. List available themes +bin/magento mageforge:theme:list -### Frontend Inspector 🕵️ +# 2. Build a theme +bin/magento mageforge:theme:build Magento/luma -The **MageForge Inspector** is a powerful developer tool that allows you to inspect Magento blocks, templates, and performance metrics directly in your browser. +# 3. Watch for changes (development mode) +bin/magento mageforge:theme:watch Magento/luma +``` -**Key Features:** -- **Structure Analysis**: View template paths, block classes, and module names for any element. -- **Performance Metrics**: See PHP render times and cache status (lifetime, tags). -- **Web Vitals**: Monitor LCP, CLS, and INP metrics per element. -- **Accessibility Checks**: Inspect ARIA roles, contrast ratios, and alt text. +See [Commands Reference](./docs/commands_reference.md) for the full command list with options and examples. -**How to use:** +## Frontend Inspector 🕵️ -1. **Enable the Inspector in the CLI**: - ```bash - bin/magento mageforge:theme:inspector enable - ``` - *(Note: Requires Magento Developer Mode)* +The MageForge Inspector lets you inspect Magento blocks, templates, and performance metrics directly in your browser. -2. **Enable the Inspector in Magento Admin Settings** -You can activate the Inspector in Magento Admin under `Stores > Configuration > MageForge > Frontend Inspector`. +**Features:** +- Template paths, block classes, and module names +- PHP render times and cache status (lifetime, tags) +- Web Vitals: LCP, CLS, INP per element +- Accessibility checks: ARIA roles, contrast ratios, alt text -3. **Usage in Browser**: - - **Toggle**: Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (macOS). - - **Inspect**: Hover over elements to see details. Click to lock the inspector on a specific block. +#### Screenshot +![Mageforge Toolbar](./.github/assets/toolbar.jpeg) -To disable the inspector: +**Enable:** ```bash -bin/magento mageforge:theme:inspector disable +bin/magento mageforge:theme:inspector enable ``` +*(Requires Developer Mode. Can also be enabled in Admin: `Stores > Configuration > MageForge > Frontend Inspector`)* -> **Note:** The Inspector is currently not compatible with **Magewire** components. Magewire blocks are automatically excluded from inspection to prevent rendering errors. +**Use in Browser:** +- Toggle: `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (macOS) +- Hover over elements to inspect; click to lock on a specific block ---- +> **Note:** Not compatible with Magewire components (automatically excluded). -## Additional Documentation +## Commands Reference -- [Commands Documentation](./docs/commands.md) - Detailed command reference -- [Advanced Usage Guide](./docs/advanced_usage.md) - Tips, tricks and troubleshooting -- [Custom Theme Builders Documentation](./docs/custom_theme_builders.md) - Extend MageForge for your custom themes -- [Development Guide](./docs/development.md) - Local dev environment setup, workflows, and contribution guide +See the dedicated [Commands Reference](./docs/commands_reference.md) for complete documentation of all MageForge commands, including: -## Support +- Theme commands (`list`, `build`, `watch`, `clean`, `inspector`) +- Hyvä commands (`tokens`, `compatibility:check`) +- System commands (`version`, `check`) +- Options, arguments, and usage examples -- **Report Bugs/Features**: [GitHub Issues](https://github.com/OpenForgeProject/mageforge/issues) -- **Discussions**: [GitHub Discussions](https://github.com/OpenForgeProject/mageforge/discussions) -- **Contributing**: See [Contributing Guidelines](./CONTRIBUTING.md) +## Documentation -> **Want to contribute?** Check out the [Development Guide](./docs/development.md) for environment setup, workflow, and coding standards. +- [Commands Reference](./docs/commands_reference.md) — Full command documentation +- [Advanced Usage](./docs/advanced_usage.md) — Tips, tricks, and troubleshooting +- [Custom Theme Builders](./docs/custom_theme_builders.md) — Extend MageForge for custom themes +- [Development Guide](./docs/development.md) — Local dev setup, workflow, and contribution guide + +## Support -## Project Information +- **Bugs / Features:** [GitHub Issues](https://github.com/OpenForgeProject/mageforge/issues) +- **Discussions:** [GitHub Discussions](https://github.com/OpenForgeProject/mageforge/discussions) +- **Contributing:** See [Contributing Guidelines](./CONTRIBUTING.md) -- **License**: [LICENSE](LICENSE) -- **Changelog**: [CHANGELOG](CHANGELOG.md) ## Credits @@ -176,4 +127,12 @@ MageForge uses the following third-party libraries: --- +## Special Thanks + +A big thank you to **[e3n-team](https://github.com/e3n-team)** for their continuous support and collaboration in the further development of MageForge. + +Your contributions have been invaluable! + +--- + Thank you for using MageForge! diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md deleted file mode 100644 index 3134c44b..00000000 --- a/docs/advanced_usage.md +++ /dev/null @@ -1,149 +0,0 @@ -# MageForge Advanced Usage - -This document provides detailed information and advanced tips for using MageForge effectively in your Magento 2 development workflow. - -## Theme Development Tips - -### Command Efficiency - -- Alternative aliases for common commands: - - `frontend:build` for `mageforge:theme:build` - - `frontend:watch` for `mageforge:theme:watch` - -Check `bin/magento mageforge` for a full list of available commands. - -### Development Workflow - -1. **System Check**: Before starting development, run a system check: - ```bash - bin/magento mageforge:system:check - ``` - -2. **Enhanced Output**: Use the `-v` option for more detailed information during builds: - ```bash - bin/magento mageforge:theme:build -v - ``` - -3. **Hot-reloading**: Watch mode automatically detects changes and rebuilds: - - For LESS files in standard Magento themes - - For Tailwind-based templates in Hyvä themes - - For custom CSS implementations - -## Theme Type Specifics - -### Standard Magento Themes (LESS) - -For traditional LESS-based Magento themes, MageForge handles: -- LESS compilation via Grunt -- Source map generation -- Minification for production - -#### Vendor Themes - -MageForge automatically detects themes installed via Composer (located in `vendor/` directory): -- **Build mode**: Skips all Grunt/Node.js steps as vendors themes have pre-built assets -- **Watch mode**: Returns an error as vendor themes are read-only and cannot be modified - -This prevents accidental modification attempts and ensures build process stability. - -#### 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: -- Automatic TailwindCSS compilation -- PurgeCSS optimization -- Component scanning - -### Custom Tailwind CSS Implementations - -For custom Tailwind setups (non-Hyvä), MageForge supports: -- Custom Tailwind configuration -- PostCSS processing -- Custom directory structures - -### Avanta B2B Themes - -Avanta is a B2B theme built on top of Hyvä. Because MageForge detects Hyvä themes via `etc/hyva-themes.json`, Avanta themes are automatically recognised and built using the Hyvä builder — no additional configuration required. - -```bash -bin/magento mageforge:theme:build Vendor/avanta -``` - -All Hyvä builder features apply: TailwindCSS compilation, PurgeCSS optimisation, and watch mode. - -## Performance Optimization - -### Build Multiple Themes in One Pass - -`mageforge:theme:build` accepts multiple theme codes, so you can build several themes without re-running the command: - -```bash -bin/magento mageforge:theme:build Vendor/theme1 Vendor/theme2 -``` - -You can also pass a vendor prefix to build all themes from that vendor at once: - -```bash -bin/magento mageforge:theme:build Hyva -``` - -### Use Watch Mode During Development - -Instead of triggering full rebuilds manually, use watch mode. It detects file changes and recompiles only what is needed, keeping feedback loops short: - -```bash -bin/magento mageforge:theme:watch Vendor/theme -``` - -### Verbose Output for Debugging Slow Builds - -Add `-v` to see each step's timing and output, which helps identify bottlenecks: - -```bash -bin/magento mageforge:theme:build Vendor/theme -v -``` - -### Vendor Themes Are Built Instantly - -Themes installed via Composer (in the `vendor/` directory) are detected automatically. MageForge skips all Node.js and Grunt steps for them, as their assets are pre-built. Building a vendor theme only runs static content deployment and cache clean. - -### Themes Without Node.js/Grunt - -Themes that omit `package.json` / `Gruntfile.js` also skip the Node.js pipeline entirely, resulting in significantly faster builds (static content deployment and cache clean only). - -## Troubleshooting -Common issues and solutions: - -1. **Build Failures**: - - Ensure Node.js is installed and available - - Check for syntax errors in LESS or CSS files - - Verify Tailwind configuration is valid - -2. **Watch Mode Issues**: - - Check file permissions - - Ensure no conflicting processes are running - -3. **Integration Problems**: - - Clear Magento cache after theme builds - - Verify theme registration in Magento - -For more help, open an issue on [GitHub Issues](https://github.com/OpenForgeProject/mageforge/issues) or start a discussion on [GitHub Discussions](https://github.com/OpenForgeProject/mageforge/discussions). diff --git a/docs/commands.md b/docs/commands.md deleted file mode 100644 index bf9214f6..00000000 --- a/docs/commands.md +++ /dev/null @@ -1,516 +0,0 @@ -# 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**: - -```bash -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**: - -```bash -bin/magento mageforge:theme:build [...] -``` - -**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**: - -```bash -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**: - -```bash -bin/magento mageforge:theme:clean [...] -``` - -**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**: - -```bash -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**: - -```bash -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**: - -```bash -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): - -```bash -# 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**: - -```bash -# 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)_: - -- `] -``` - -**Aliases**: - -- `m:h:t` - -**Arguments**: - -- `themeCode` (optional) - Theme code in format Vendor/theme - -**Examples**: - -```bash -# 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**: - -```bash -# 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. diff --git a/docs/commands_reference.md b/docs/commands_reference.md new file mode 100644 index 00000000..9efd860f --- /dev/null +++ b/docs/commands_reference.md @@ -0,0 +1,205 @@ +# MageForge Commands Reference + +Complete reference of all CLI commands provided by the MageForge module. + +## Quick Overview + +| Group | Command | Description | Aliases | +|-------|---------|-------------|---------| +| **Theme** | `mageforge:theme:list` | List all available Magento themes | `frontend:list` | +| **Theme** | `mageforge:theme:build` | Build selected themes (CSS/TailwindCSS) | `frontend:build` | +| **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) | — | +| **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` | +| **System** | `mageforge:system:check` | Display system information (PHP, Node.js, DB, etc.) | `system:check` | + +--- + +## Theme Commands + +### `mageforge:theme:list` + +Lists all available Magento themes in the installation. + +```bash +bin/magento mageforge:theme:list +# or alias +bin/magento frontend:list +``` + +**Output:** Displays a table with Code, Title, and Path for each theme. + +--- + +### `mageforge:theme:build` + +Builds selected themes by compiling assets (CSS/TailwindCSS) and deploying static content. + +```bash +bin/magento mageforge:theme:build [ ...] +bin/magento frontend:build Magento/luma Magento/blank +``` + +**Arguments:** +- `themeCodes` — One or more theme codes in format `Vendor/theme`. Accepts wildcards like `Magento/*`. + +**Behavior:** +- If no theme codes are provided, an interactive prompt lets you select themes. +- For each theme, the appropriate builder is determined automatically (Hyvä, TailwindCSS, Magento Standard, etc.). +- Displays a summary of built themes and execution time. + +--- + +### `mageforge:theme:watch` + +Watches theme files for changes and automatically rebuilds when modifications are detected. + +```bash +bin/magento mageforge:theme:watch +bin/magento frontend:watch Magento/luma +``` + +**Arguments:** +- `themeCode` — Optional. Theme to watch in format `Vendor/theme`. If omitted, an interactive prompt appears. + +**Options:** +- `-t, --theme=VALUE` — Alternative way to specify the theme code. + +**Behavior:** +- Runs indefinitely until interrupted (Ctrl+C). +- Monitors source files (SCSS, JS, etc.) and triggers rebuilds on change. +- Useful for active theme development. + +--- + +### `mageforge:theme:clean` + +Cleans theme static files and cache directories. + +```bash +bin/magento mageforge:theme:clean [ ...] +bin/magento mageforge:theme:clean --all +bin/magento mageforge:theme:clean --dry-run +``` + +**Arguments:** +- `themeCodes` — Optional. One or more theme codes to clean. + +**Options:** +- `-a, --all` — Clean all themes. +- `--dry-run` — Show what would be cleaned without actually deleting anything. + +--- + +### `mageforge:theme:inspector` + +Manage the MageForge Frontend Inspector (developer tool for inspecting blocks, templates, and performance metrics). + +```bash +bin/magento mageforge:theme:inspector enable +bin/magento mageforge:theme:inspector disable +bin/magento mageforge:theme:inspector status +``` + +**Arguments:** +- `action` — Required. One of: `enable`, `disable`, `status`. + +**Notes:** +- Requires Magento Developer Mode for enabling. +- Can also be toggled via Admin: `Stores > Configuration > MageForge > Frontend Inspector`. +- Browser shortcut: `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Option+I` (macOS). +- Not compatible with Magewire components (automatically excluded). + +--- + +## Hyvä Commands + +### `mageforge:hyva:tokens` + +Generate Hyvä design tokens from `design.tokens.json` or `hyva.config.json`. + +```bash +bin/magento mageforge:hyva:tokens [] +bin/magento hyva:tokens Hyvä/thema +``` + +**Arguments:** +- `themeCode` — Optional. Theme code in format `Vendor/theme`. If omitted, an interactive prompt appears. + +**Output:** Creates a `generated/hyva-tokens.css` file from the design tokens configuration. + +--- + +### `mageforge:hyva:compatibility:check` + +Scans Magento modules for Hyvä theme compatibility issues (RequireJS, Knockout.js, jQuery, UI Components). + +```bash +bin/magento mageforge:hyva:compatibility:check +bin/magento hyva:check +``` + +**Options:** +- `-a, --show-all` — Show all modules including compatible ones. +- `-t, --third-party-only` — Check only third-party modules (exclude Magento_*). +- `--include-vendor` — Include Magento core modules in the check. +- `--detailed` — Show detailed compatibility information. + +**Output:** Displays a table with compatibility status per module. + +--- + +## System Commands + +### `mageforge:system:version` + +Displays the current installed MageForge version and checks for the latest release. + +```bash +bin/magento mageforge:system:version +bin/magento system:version +``` + +**Output:** Shows Module Version and Latest Version (fetched from GitHub API). + +--- + +### `mageforge:system:check` + +Displays comprehensive system information for troubleshooting and setup validation. + +```bash +bin/magento mageforge:system:check +bin/magento system:check +``` + +**Reports:** +- PHP version and extensions +- Magento version +- Database type and version (MySQL/MariaDB) +- Node.js version (with LTS reference) +- Composer and npm versions +- Git version +- Xdebug status +- Redis status +- Search engine status (Elasticsearch/OpenSearch) +- Disk space + +--- + +## Command Groups Summary + +``` +mageforge:theme:list → List available themes +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:hyva:tokens → Generate Hyvä design tokens +mageforge:hyva:compatibility:check → Check Hyvä compatibility +mageforge:system:version → Show module version +mageforge:system:check → System diagnostics +``` diff --git a/docs/custom_theme_builders.md b/docs/custom_theme_builders.md index 47f3045d..7afcd5b6 100644 --- a/docs/custom_theme_builders.md +++ b/docs/custom_theme_builders.md @@ -101,7 +101,7 @@ class Builder implements BuilderInterface return file_exists($themePath . '/your-custom-identifier.json'); } - public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool + public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool { // Check if this builder is responsible for the theme if (!$this->detect($themePath)) { @@ -137,7 +137,7 @@ class Builder implements BuilderInterface return true; } - public function watch(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool + public function watch(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool { // Check if this builder is responsible for the theme if (!$this->detect($themePath)) { @@ -238,7 +238,7 @@ public function detect(string $themePath): bool This method performs the actual build process. You can implement any steps required for your theme type: ```php -public function build(string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool +public function build(string $themeCode, string $themePath, SymfonyStyle $io, OutputInterface $output, bool $isVerbose): bool { // Build process examples: From be79458a143bfd8c504e2ffe5e2c52caae44be3a Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:30:13 +0200 Subject: [PATCH 2/6] [feat] update support status for theme types in README --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c445e6bc..d9bf3239 100644 --- a/README.md +++ b/README.md @@ -31,12 +31,12 @@ MageForge is a powerful CLI toolkit for Magento 2 front-end development. It simp | Theme Type | Support Status | | ------------------------------- | ---------------------------------------------------------- | -| 🎯 Magento Standard | ✅ Fully Supported | -| 🚀 Hyvä (TailwindCSS 3.x / 4.x) | ✅ Fully Supported | -| 🛒 Hyvä Checkout | ✅ Fully Supported -| 🔄 Hyvä Fallback | ✅ Fully Supported | -| 🎨 Custom TailwindCSS (no Hyvä) | ✅ Fully Supported | -| 💼 Avanta B2B | ✅ Fully Supported | +| 🎯 Magento Standard | ✅ Supported | +| 🚀 Hyvä (TailwindCSS 3.x / 4.x) | ✅ Supported | +| 🛒 Hyvä Checkout | ✅ Supported | +| 🔄 Hyvä Fallback | ✅ Supported | +| 🎨 Custom TailwindCSS (no Hyvä) | ✅ Supported | +| 💼 Avanta B2B | ✅ Supported | | 🥰 Your Custom Theme | [Create your own Builder](./docs/custom_theme_builders.md) | ## Installation From 529d0c0f8d592c0cccdea66b6ecefd7d2d7b713c Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:38:14 +0200 Subject: [PATCH 3/6] fix: remove advanced usage documentation link from README --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index d9bf3239..1c171f49 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,6 @@ See the dedicated [Commands Reference](./docs/commands_reference.md) for complet ## Documentation - [Commands Reference](./docs/commands_reference.md) — Full command documentation -- [Advanced Usage](./docs/advanced_usage.md) — Tips, tricks, and troubleshooting - [Custom Theme Builders](./docs/custom_theme_builders.md) — Extend MageForge for custom themes - [Development Guide](./docs/development.md) — Local dev setup, workflow, and contribution guide From 119c928da660cfbf8fb8d26fccccb2aa8ceed886 Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:42:24 +0200 Subject: [PATCH 4/6] feat: update command example for hyva:tokens to specify theme requirements --- docs/commands_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commands_reference.md b/docs/commands_reference.md index 9efd860f..cdebb521 100644 --- a/docs/commands_reference.md +++ b/docs/commands_reference.md @@ -123,7 +123,7 @@ Generate Hyvä design tokens from `design.tokens.json` or `hyva.config.json`. ```bash bin/magento mageforge:hyva:tokens [] -bin/magento hyva:tokens Hyvä/thema +bin/magento hyva:tokens Vendor/theme # must be a Hyvä theme with design tokens configured ``` **Arguments:** From b8c9d085671105173725be4cb78c8c53240ed388 Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:44:22 +0200 Subject: [PATCH 5/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/commands_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commands_reference.md b/docs/commands_reference.md index cdebb521..84ab196d 100644 --- a/docs/commands_reference.md +++ b/docs/commands_reference.md @@ -123,7 +123,7 @@ Generate Hyvä design tokens from `design.tokens.json` or `hyva.config.json`. ```bash bin/magento mageforge:hyva:tokens [] -bin/magento hyva:tokens Vendor/theme # must be a Hyvä theme with design tokens configured +bin/magento hyva:tokens Hyva/default ``` **Arguments:** From abffe910258a7346c3b865df4cf619744e8617fe Mon Sep 17 00:00:00 2001 From: Mathias Elle Date: Wed, 3 Jun 2026 20:52:26 +0200 Subject: [PATCH 6/6] feat: update README to fix links and remove emojis from theme types section --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 1c171f49..250a603d 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ MageForge is a powerful CLI toolkit for Magento 2 front-end development. It simp ## Table of Contents - [Requirements](#requirements) -- [Supported Theme Types](#supported-theme-types-) +- [Supported Theme Types](#supported-theme-types) - [Installation](#installation) - [Quick Start](#quick-start) -- [Frontend Inspector](#frontend-inspector-) +- [Frontend Inspector](#frontend-inspector) - [Commands Reference](#commands-reference) - [Documentation](#documentation) - [Support](#support) @@ -27,17 +27,17 @@ MageForge is a powerful CLI toolkit for Magento 2 front-end development. It simp - Node.js (LTS recommended) - Composer -## Supported Theme Types 🎨 +## Supported Theme Types | Theme Type | Support Status | | ------------------------------- | ---------------------------------------------------------- | -| 🎯 Magento Standard | ✅ Supported | -| 🚀 Hyvä (TailwindCSS 3.x / 4.x) | ✅ Supported | -| 🛒 Hyvä Checkout | ✅ Supported | -| 🔄 Hyvä Fallback | ✅ Supported | -| 🎨 Custom TailwindCSS (no Hyvä) | ✅ Supported | -| 💼 Avanta B2B | ✅ Supported | -| 🥰 Your Custom Theme | [Create your own Builder](./docs/custom_theme_builders.md) | +| Magento Standard | ✅ Supported | +| Hyvä (TailwindCSS 3.x / 4.x) | ✅ Supported | +| Hyvä Checkout | ✅ Supported | +| Hyvä Fallback | ✅ Supported | +| Custom TailwindCSS (no Hyvä) | ✅ Supported | +| Avanta B2B | ✅ Supported | +| Your Custom Theme | [Create your own Builder](./docs/custom_theme_builders.md) | ## Installation @@ -69,7 +69,7 @@ bin/magento mageforge:theme:watch Magento/luma See [Commands Reference](./docs/commands_reference.md) for the full command list with options and examples. -## Frontend Inspector 🕵️ +## Frontend Inspector The MageForge Inspector lets you inspect Magento blocks, templates, and performance metrics directly in your browser.