chore: initial workflow implementation

Signed-off-by: Sebastian Krupinski <root@LAPTOP-7DVOR6NC>
2026-02-15 16:13:08 -05:00
parent cbeb999b18
commit 966aa9f099
3 changed files with 1433 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,407 @@
-# action-module-install
+# Nodarx Module Install Action
+
+Install custom PHP/Vue modules from git repositories with automatic dependency resolution.
+
+This GitHub Action clones module repositories, resolves dependencies, and installs both PHP (Composer) and Node.js (npm) dependencies in the correct order.
+
+## Features
+
+- 🔗 **Dependency Resolution**: Automatically orders modules based on their dependencies
+- 📦 **Multi-Language Support**: Handles both PHP (Composer) and Node.js (npm) projects
+- 🔄 **Flexible**: Support for custom branches, tags, or commits
+- ✅ **Validation**: Detects circular dependencies and validates module configuration
+- 🎯 **Simple**: Just provide a JSON array of modules and their dependencies
+
+## Quick Start
+
+```yaml
+name: Deploy with Modules
+
+on: [push]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      # Install server environment (PHP + Node.js)
+      - uses: Nodarx/action-server-install@v1
+        with:
+          install-php: 'true'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+      
+      # Install modules with dependencies
+      - uses: Nodarx/action-module-install@v1
+        with:
+          modules: |
+            [
+              {"name": "mail_manager", "repo": "https://git.ktrix.dev/Nodarx/mail_manager"},
+              {"name": "provider_jmapc", "repo": "https://git.ktrix.dev/Nodarx/provider_jmapc"},
+              {"name": "mail", "repo": "https://git.ktrix.dev/Nodarx/mail", "dependencies": ["mail_manager", "provider_jmapc"]}
+            ]
+```
+
+## Inputs
+
+| Input | Description | Required | Default |
+|-------|-------------|----------|---------|
+| `modules` | JSON array of modules to install (see [Module Schema](#module-schema)) | Yes | - |
+| `install-path` | Base directory where modules will be installed | No | `./modules` |
+| `skip-dependencies-check` | Skip dependency validation (not recommended) | No | `false` |
+
+## Outputs
+
+| Output | Description | Example |
+|--------|-------------|---------|
+| `installed-modules` | Comma-separated list of installed module names in installation order | `mail_manager,provider_jmapc,mail` |
+| `install-path` | Path where modules were installed | `./modules` |
+| `status` | Installation status | `success` |
+
+## Module Schema
+
+Each module in the `modules` array should follow this structure:
+
+```json
+{
+  "name": "module-name",           // Required: Unique module identifier
+  "repo": "https://...",            // Required: Git repository URL
+  "branch": "main",                 // Optional: Branch, tag, or commit (default: main)
+  "dependencies": ["module1"]       // Optional: Array of module names this module depends on
+}
+```
+
+### Module Schema Examples
+
+**Minimal Module (No Dependencies)**
+```json
+{
+  "name": "standalone-module",
+  "repo": "https://git.ktrix.dev/Nodarx/standalone"
+}
+```
+
+**Module with Branch Specification**
+```json
+{
+  "name": "beta-module",
+  "repo": "https://git.ktrix.dev/Nodarx/beta",
+  "branch": "develop"
+}
+```
+
+**Module with Dependencies**
+```json
+{
+  "name": "mail",
+  "repo": "https://git.ktrix.dev/Nodarx/mail",
+  "branch": "main",
+  "dependencies": ["mail_manager", "provider_jmapc"]
+}
+```
+
+## Usage Examples
+
+### Single Module
+
+```yaml
+- uses: Nodarx/action-module-install@v1
+  with:
+    modules: |
+      [
+        {"name": "auth", "repo": "https://git.ktrix.dev/Nodarx/auth"}
+      ]
+```
+
+### Linear Dependencies (A → B → C)
+
+```yaml
+- uses: Nodarx/action-module-install@v1
+  with:
+    modules: |
+      [
+        {"name": "core", "repo": "https://git.ktrix.dev/Nodarx/core"},
+        {"name": "api", "repo": "https://git.ktrix.dev/Nodarx/api", "dependencies": ["core"]},
+        {"name": "web", "repo": "https://git.ktrix.dev/Nodarx/web", "dependencies": ["api"]}
+      ]
+```
+Installation order: `core` → `api` → `web`
+
+### Diamond Dependencies (A,B → C; C → D)
+
+```yaml
+- uses: Nodarx/action-module-install@v1
+  with:
+    modules: |
+      [
+        {"name": "utils", "repo": "https://git.ktrix.dev/Nodarx/utils"},
+        {"name": "storage", "repo": "https://git.ktrix.dev/Nodarx/storage"},
+        {"name": "database", "repo": "https://git.ktrix.dev/Nodarx/database", "dependencies": ["utils", "storage"]},
+        {"name": "api", "repo": "https://git.ktrix.dev/Nodarx/api", "dependencies": ["database"]}
+      ]
+```
+Installation order: `utils,storage` → `database` → `api`
+
+### Mail System Example (Real-World)
+
+```yaml
+- uses: Nodarx/action-server-install@v1
+  with:
+    install-php: 'true'
+    install-node: 'true'
+    php-version: '8.5'
+    node-version: '24'
+
+- uses: Nodarx/action-module-install@v1
+  id: modules
+  with:
+    modules: |
+      [
+        {
+          "name": "mail_manager",
+          "repo": "https://git.ktrix.dev/Nodarx/mail_manager",
+          "branch": "main"
+        },
+        {
+          "name": "provider_jmapc",
+          "repo": "https://git.ktrix.dev/Nodarx/provider_jmapc",
+          "branch": "stable1"
+        },
+        {
+          "name": "mail",
+          "repo": "https://git.ktrix.dev/Nodarx/mail",
+          "branch": "main",
+          "dependencies": ["mail_manager", "provider_jmapc"]
+        }
+      ]
+    install-path: './modules'
+
+- name: Verify installation
+  run: |
+    echo "Installed: ${{ steps.modules.outputs.installed-modules }}"
+    ls -la ./modules/
+```
+
+### Different Branches per Module
+
+```yaml
+- uses: Nodarx/action-module-install@v1
+  with:
+    modules: |
+      [
+        {"name": "core", "repo": "https://git.ktrix.dev/Nodarx/core", "branch": "v2.0"},
+        {"name": "plugin", "repo": "https://git.ktrix.dev/Nodarx/plugin", "branch": "develop"},
+        {"name": "theme", "repo": "https://git.ktrix.dev/Nodarx/theme", "branch": "stable1"}
+      ]
+```
+
+### Custom Install Path
+
+```yaml
+- uses: Nodarx/action-module-install@v1
+  with:
+    install-path: './custom/modules/directory'
+    modules: |
+      [
+        {"name": "module1", "repo": "https://git.ktrix.dev/Nodarx/module1"}
+      ]
+```
+
+## How It Works
+
+1. **Validation**: Validates JSON structure and checks that all dependencies are defined
+2. **Dependency Resolution**: Uses topological sort to determine correct installation order
+3. **Cloning**: Clones each module repository in dependency order
+4. **Installation**: Auto-detects and runs:
+   - `composer install` for modules with `composer.json`
+   - `npm install` or `npm ci` for modules with `package.json`
+5. **Verification**: Verifies all modules installed successfully
+
+## Dependency Resolution
+
+The action automatically determines the correct installation order:
+
+```
+Input modules:
+- mail (depends on: mail_manager, provider_jmapc)
+- mail_manager (no dependencies)
+- provider_jmapc (no dependencies)
+
+Installation order:
+1. mail_manager
+2. provider_jmapc  
+3. mail
+```
+
+Dependencies are installed **before** their dependents, ensuring all required modules are available when needed.
+
+## Error Handling
+
+The action will fail with descriptive errors for:
+
+- ❌ **Invalid JSON**: Syntax errors in modules input
+- ❌ **Missing Fields**: Modules without `name` or `repo`
+- ❌ **Circular Dependencies**: A → B → A
+- ❌ **Missing Dependencies**: Module depends on undefined module
+- ❌ **Clone Failures**: Repository not accessible or branch doesn't exist
+- ❌ **Install Failures**: Composer or npm installation errors
+- ❌ **Missing Prerequisites**: PHP/Composer or Node/npm not installed
+
+## Prerequisites
+
+Before using this action, ensure PHP and/or Node.js are installed:
+
+```yaml
+- uses: Nodarx/action-server-install@v1
+  with:
+    install-php: 'true'    # If modules use Composer
+    install-node: 'true'   # If modules use npm
+```
+
+Or use standard setup actions:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: '24'
+
+- uses: shivammathur/setup-php@v2
+  with:
+    php-version: '8.5'
+    tools: composer:v2
+```
+
+## Troubleshooting
+
+### Circular Dependency Error
+
+```
+Error: Circular dependency detected. Cannot determine installation order.
+```
+
+**Solution**: Review your dependencies to remove circular references. Example:
+```
+❌ moduleA depends on moduleB, moduleB depends on moduleA
+✅ moduleA depends on moduleB, moduleB has no dependencies
+```
+
+### Missing Dependency Error
+
+```
+Error: The following dependencies are referenced but not defined: module_x
+```
+
+**Solution**: Add the missing module to your modules array:
+```json
+[
+  {"name": "module_x", "repo": "https://..."},
+  {"name": "dependent", "repo": "https://...", "dependencies": ["module_x"]}
+]
+```
+
+### Composer/npm Not Found
+
+```
+Error: composer not found. Please ensure PHP and Composer are installed
+```
+
+**Solution**: Install PHP/Node.js before this action:
+```yaml
+- uses: Nodarx/action-server-install@v1
+  with:
+    install-php: 'true'
+    install-node: 'true'
+```
+
+### Clone Failed (Branch Not Found)
+
+```
+Error: Failed to clone module_name from https://... (branch: xyz)
+```
+
+**Solution**: Verify the branch exists in the repository. Use `main`, `master`, or a valid branch/tag name.
+
+## Complete Workflow Example
+
+```yaml
+name: Deploy Application with Modules
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup server environment
+        uses: Nodarx/action-server-install@v1
+        with:
+          install-php: 'true'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+      
+      - name: Install application modules
+        id: install-modules
+        uses: Nodarx/action-module-install@v1
+        with:
+          modules: |
+            [
+              {
+                "name": "mail_manager",
+                "repo": "https://git.ktrix.dev/Nodarx/mail_manager",
+                "branch": "main"
+              },
+              {
+                "name": "provider_jmapc",
+                "repo": "https://git.ktrix.dev/Nodarx/provider_jmapc",
+                "branch": "stable1"
+              },
+              {
+                "name": "mail",
+                "repo": "https://git.ktrix.dev/Nodarx/mail",
+                "branch": "main",
+                "dependencies": ["mail_manager", "provider_jmapc"]
+              },
+              {
+                "name": "calendar",
+                "repo": "https://git.ktrix.dev/Nodarx/calendar",
+                "branch": "main",
+                "dependencies": ["mail_manager"]
+              }
+            ]
+          install-path: './server/modules'
+      
+      - name: Display installation results
+        run: |
+          echo "Installation Status: ${{ steps.install-modules.outputs.status }}"
+          echo "Installed Modules: ${{ steps.install-modules.outputs.installed-modules }}"
+          echo "Install Path: ${{ steps.install-modules.outputs.install-path }}"
+          
+          echo ""
+          echo "Module directories:"
+          ls -la ${{ steps.install-modules.outputs.install-path }}
+      
+      - name: Run application tests
+        run: |
+          cd ./server
+          npm test
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Author
+
+Created by [Nodarx](https://github.com/Nodarx)