Feat/refactoring-module-menu (#22733)

apps/installer/includes/modules-manager/README.md

@@ -0,0 +1,188 @@
+# AzerothCore Module Manager
+
+This directory contains the module management system for AzerothCore, providing advanced functionality for installing, updating, and managing server modules.
+
+## 🚀 Features
+
+- **Advanced Syntax**: Support for `repo[:dirname][@branch[:commit]]` format
+- **Cross-Format Recognition**: Intelligent matching across URLs, SSH, and simple names
+- **Custom Directory Naming**: Prevent conflicts with custom directory names
+- **Duplicate Prevention**: Smart detection and prevention of duplicate installations
+- **Multi-Host Support**: GitHub, GitLab, and other Git hosts
+
+## 📁 File Structure
+
+```
+modules-manager/
+├── modules.sh              # Core module management functions
+└── README.md               # This documentation file
+```
+
+## 🔧 Module Specification Syntax
+
+The module manager supports flexible syntax for specifying modules:
+
+### New Syntax Format
+```bash
+repo[:dirname][@branch[:commit]]
+```
+
+### Examples
+
+| Specification | Description |
+|---------------|-------------|
+| `mod-transmog` | Simple module name, uses default branch and directory |
+| `mod-transmog:my-custom-dir` | Custom directory name |
+| `mod-transmog@develop` | Specific branch |
+| `mod-transmog:custom@develop:abc123` | Custom directory, branch, and commit |
+| `https://github.com/owner/repo.git@main` | Full URL with branch |
+| `git@github.com:owner/repo.git:custom-dir` | SSH URL with custom directory |
+
+## 🎯 Usage Examples
+
+### Installing Modules
+
+```bash
+# Simple module installation
+./acore.sh module install mod-transmog
+
+# Install with custom directory name
+./acore.sh module install mod-transmog:my-transmog-dir
+
+# Install specific branch
+./acore.sh module install mod-transmog@develop
+
+# Install with full specification
+./acore.sh module install mod-transmog:custom-dir@develop:abc123
+
+# Install from URL
+./acore.sh module install https://github.com/azerothcore/mod-transmog.git@main
+
+# Install multiple modules
+./acore.sh module install mod-transmog mod-eluna:custom-eluna
+
+# Install all modules from list
+./acore.sh module install --all
+```
+
+### Updating Modules
+
+```bash
+# Update specific module
+./acore.sh module update mod-transmog
+
+# Update all modules
+./acore.sh module update --all
+
+# Update with branch specification
+./acore.sh module update mod-transmog@develop
+```
+
+### Removing Modules
+
+```bash
+# Remove by simple name (cross-format recognition)
+./acore.sh module remove mod-transmog
+
+# Remove by URL (recognizes same module)
+./acore.sh module remove https://github.com/azerothcore/mod-transmog.git
+
+# Remove multiple modules
+./acore.sh module remove mod-transmog mod-eluna
+```
+
+### Searching Modules
+
+```bash
+# Search for modules
+./acore.sh module search transmog
+
+# Search with multiple terms
+./acore.sh module search auction house
+
+# Show all available modules
+./acore.sh module search
+```
+
+## 🔍 Cross-Format Recognition
+
+The system intelligently recognizes the same module across different specification formats:
+
+```bash
+# These all refer to the same module:
+mod-transmog
+azerothcore/mod-transmog
+https://github.com/azerothcore/mod-transmog.git
+git@github.com:azerothcore/mod-transmog.git
+```
+
+This allows:
+- Installing with one format and removing with another
+- Preventing duplicates regardless of specification format
+- Consistent module tracking across different input methods
+
+## 🛡️ Conflict Prevention
+
+The system prevents common conflicts:
+
+### Directory Conflicts
+```bash
+# If 'mod-transmog' directory already exists:
+$ ./acore.sh module install mod-transmog:mod-transmog
+Error: Directory 'mod-transmog' already exists.
+Possible solutions:
+  1. Use a different directory name: mod-transmog:my-custom-name
+  2. Remove the existing directory first
+  3. Use the update command if this is the same module
+```
+
+## 🔄 Integration
+
+### Including in Scripts
+```bash
+# Source the module functions
+source "$AC_PATH_INSTALLER/includes/modules-manager/modules.sh"
+
+# Use module functions
+inst_module_install "mod-transmog:custom-dir@develop"
+```
+
+### Testing
+The module system is tested through the main installer test suite:
+```bash
+./apps/installer/test/test_module_commands.bats
+```
+
+## 📋 Module List Format
+
+Modules are tracked in `conf/modules.list` with the format:
+```
+# Comments start with #
+repo_reference branch commit
+
+# Examples:
+azerothcore/mod-transmog master abc123def456
+https://github.com/custom/mod-custom.git develop def456abc789
+mod-eluna:custom-eluna-dir main 789abc123def
+```
+## 🔧 Configuration
+
+### Environment Variables
+- `MODULES_LIST_FILE`: Override default modules list path
+- `J_PATH_MODULES`: Modules installation directory
+- `AC_PATH_ROOT`: AzerothCore root path
+
+### Default Paths
+- Modules list: `$AC_PATH_ROOT/conf/modules.list`
+
+## 🤝 Contributing
+
+When modifying the module manager:
+
+1. Maintain backwards compatibility
+2. Update tests in `test_module_commands.bats`
+3. Update this documentation
+4. Test cross-format recognition thoroughly
+5. Ensure helpful error messages
+
+