MokoOnyx v01.00.00 — initial release (successor to MokoCassiopeia)

All files renamed from mokocassiopeia to mokoonyx.
Update server points to MokoOnyx repo.
Bridge migration removed (clean standalone template).
Version reset to 01.00.00.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/JOOMLA_DEVELOPMENT.md

@@ -0,0 +1,376 @@
+# Joomla Development Workflows and Scripts
+
+This document describes the Joomla-aware development workflows and scripts available in this repository.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Requirements](#requirements)
+- [Scripts](#scripts)
+- [GitHub Actions Workflows](#github-actions-workflows)
+- [Testing](#testing)
+- [Code Quality](#code-quality)
+- [Deployment](#deployment)
+
+## Overview
+
+This repository includes comprehensive Joomla development workflows and scripts for:
+
+1. **Extension Packaging** - Create distributable ZIP packages
+2. **Joomla Testing** - Automated testing with multiple Joomla versions
+3. **Code Quality** - PHPStan, PHP_CodeSniffer, and compatibility checks
+4. **Deployment** - Staging and production deployment workflows
+
+## Requirements
+
+### Local Development
+
+- PHP 8.0 or higher
+- Composer (for PHPStan and PHP_CodeSniffer)
+- Node.js 18+ (for some workflows)
+- MySQL/MariaDB (for Joomla testing)
+
+### CI/CD (GitHub Actions)
+
+All requirements are automatically installed in CI/CD pipelines.
+
+## Scripts
+
+### Extension Packaging
+
+Package the Joomla template as a distributable ZIP file:
+
+```bash
+make package
+```
+
+This creates a ZIP file in the `dist` directory with all necessary template files, excluding development files.
+
+## GitHub Actions Workflows
+
+### 1. PHP Code Quality (`php_quality.yml`)
+
+Runs on every push and pull request to main branches.
+
+**Jobs:**
+- **PHP_CodeSniffer** - Checks code style and standards
+- **PHPStan** - Static analysis at level 5
+- **PHP Compatibility** - Ensures PHP 8.0+ compatibility
+
+**Matrix Testing:**
+- PHP versions: 8.0, 8.1, 8.2, 8.3
+
+**Trigger:**
+```bash
+# Automatically runs on push/PR
+git push origin dev/3.5.0
+```
+
+### 2. Joomla Testing (`joomla_testing.yml`)
+
+Tests template with multiple Joomla and PHP versions.
+
+**Jobs:**
+- **Joomla Setup** - Installs Joomla CMS
+- **Template Installation** - Installs template into Joomla
+- **Validation** - Validates template functionality
+- **Codeception** - Runs test framework
+
+**Matrix Testing:**
+- PHP versions: 8.0, 8.1, 8.2, 8.3
+- Joomla versions: 4.4 (LTS), 5.0, 5.1
+- MySQL version: 8.0
+
+**Example:**
+```bash
+# Automatically runs on push to main branches
+git push origin main
+```
+
+### 3. Deploy to Staging (`deploy_staging.yml`)
+
+Manual deployment to staging/development environments.
+
+**Parameters:**
+- `environment`: Target environment (staging, development, preview)
+- `version`: Version to deploy (optional, defaults to latest)
+
+**Usage:**
+1. Go to Actions → Deploy to Staging
+2. Click "Run workflow"
+3. Select environment and version
+4. Click "Run workflow"
+
+**Required Secrets:**
+For staging deployment, configure these repository secrets:
+- `STAGING_HOST` - SFTP server hostname
+- `STAGING_USER` - SFTP username
+- `STAGING_KEY` - SSH private key (recommended) or use `STAGING_PASSWORD`
+- `STAGING_PATH` - Remote path for deployment
+- `STAGING_PORT` - SSH port (optional, default: 22)
+
+## Testing
+
+### Codeception Framework
+
+The repository is configured with Codeception for acceptance and unit testing.
+
+#### Running Tests Locally
+
+1. Install Codeception:
+```bash
+composer global require "codeception/codeception" --with-all-dependencies
+```
+
+2. Run tests:
+```bash
+# Run all tests
+codecept run
+
+# Run acceptance tests only
+codecept run acceptance
+
+# Run unit tests only
+codecept run unit
+
+# Run with verbose output
+codecept run --debug
+```
+
+#### Test Structure
+
+```
+tests/
+├── _data/              # Test data and fixtures
+├── _output/            # Test reports and screenshots
+├── _support/           # Helper classes
+├── acceptance/         # Acceptance tests
+│   └── TemplateInstallationCest.php
+├── unit/               # Unit tests
+│   └── TemplateConfigurationTest.php
+├── acceptance.suite.yml
+└── unit.suite.yml
+```
+
+#### Writing Tests
+
+**Unit Test Example:**
+```php
+<?php
+namespace Tests\Unit;
+
+use Codeception\Test\Unit;
+
+class MyTemplateTest extends Unit
+{
+    public function testSomething()
+    {
+        $this->assertTrue(true);
+    }
+}
+```
+
+**Acceptance Test Example:**
+```php
+<?php
+namespace Tests\Acceptance;
+
+use Tests\Support\AcceptanceTester;
+
+class MyAcceptanceCest
+{
+    public function testPageLoad(AcceptanceTester $I)
+    {
+        $I->amOnPage('/');
+        $I->see('Welcome');
+    }
+}
+```
+
+## Code Quality
+
+### PHPStan
+
+Static analysis configuration in `phpstan.neon`:
+
+```bash
+# Run PHPStan locally
+phpstan analyse --configuration=phpstan.neon
+```
+
+**Configuration:**
+- Analysis level: 5
+- Target paths: `src/`
+- PHP version: 8.0+
+
+### PHP_CodeSniffer
+
+Coding standards configuration in `phpcs.xml`:
+
+```bash
+# Check code style
+phpcs --standard=phpcs.xml
+
+# Fix auto-fixable issues
+phpcbf --standard=phpcs.xml
+```
+
+**Standards:**
+- PSR-12 as base
+- PHP 8.0+ compatibility checks
+- Joomla coding conventions (when available)
+
+### Running Quality Checks Locally
+
+1. Install tools:
+```bash
+composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies
+composer global require "phpstan/phpstan:^1.0" --with-all-dependencies
+composer global require "phpcompatibility/php-compatibility:^9.0" --with-all-dependencies
+```
+
+2. Configure PHPCompatibility:
+```bash
+phpcs --config-set installed_paths ~/.composer/vendor/phpcompatibility/php-compatibility
+```
+
+3. Run checks:
+```bash
+# PHP syntax check
+make validate-required
+
+# CodeSniffer
+phpcs --standard=phpcs.xml src/
+
+# PHPStan
+phpstan analyse --configuration=phpstan.neon
+
+# PHP Compatibility
+phpcs --standard=PHPCompatibility --runtime-set testVersion 8.0- src/
+```
+
+## Deployment
+
+### Manual Deployment
+
+Use the package script to create a distribution:
+
+```bash
+# Create package
+make package
+
+# Upload to server
+scp dist/moko-cassiopeia-3.5.0-template.zip user@server:/path/to/joomla/
+```
+
+### Automated Deployment
+
+Use the GitHub Actions workflow:
+
+1. **Staging Deployment:**
+   - Go to Actions → Deploy to Staging
+   - Select "staging" environment
+   - Click "Run workflow"
+
+2. **Development Testing:**
+   - Select "development" environment
+   - Useful for quick testing without affecting staging
+
+3. **Preview Deployment:**
+   - Select "preview" environment
+   - For showcasing features before staging
+
+### Post-Deployment Steps
+
+After deployment to Joomla:
+
+1. Log in to Joomla administrator
+2. Go to System → Extensions → Discover
+3. Click "Discover" to find the template
+4. Click "Install" to complete installation
+5. Go to System → Site Templates
+6. Configure template settings
+7. Set as default template if desired
+
+## CI/CD Pipeline Details
+
+### Build Process
+
+1. **Validation** - All scripts validate before packaging
+2. **Packaging** - Create ZIP with proper structure
+3. **Testing** - Run on multiple PHP/Joomla versions
+4. **Quality** - PHPStan and PHPCS analysis
+5. **Deployment** - SFTP upload to target environment
+
+### Matrix Testing Strategy
+
+- **PHP Versions:** 8.0, 8.1, 8.2, 8.3
+- **Joomla Versions:** 4.4 LTS, 5.0, 5.1
+- **Exclusions:** PHP 8.3 not tested with Joomla 4.4 (incompatible)
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: PHP_CodeSniffer not found**
+```bash
+composer global require "squizlabs/php_codesniffer:^3.0"
+export PATH="$PATH:$HOME/.composer/vendor/bin"
+```
+
+**Issue: PHPStan errors**
+```bash
+# Increase analysis memory
+php -d memory_limit=1G $(which phpstan) analyse
+```
+
+**Issue: Joomla installation fails in CI**
+- Check MySQL service is running
+- Verify database credentials
+- Ensure PHP extensions are installed
+
+**Issue: SFTP deployment fails**
+- Verify SSH key is correctly formatted
+- Check firewall allows port 22
+- Ensure STAGING_PATH exists on server
+
+## Contributing
+
+When adding new workflows or scripts:
+
+1. Follow existing script structure
+2. Add proper error handling
+3. Include usage documentation
+4. Test with multiple PHP versions
+5. Update this documentation
+
+## Support
+
+For issues or questions:
+- Open an issue on GitHub
+- Check existing workflow runs for examples
+- Review test output in Actions tab
+
+## License
+
+All scripts and workflows are licensed under GPL-3.0-or-later, same as the main project.
+
+---
+
+## Metadata
+
+* Document: docs/JOOMLA_DEVELOPMENT.md
+* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
+* Path: /docs/JOOMLA_DEVELOPMENT.md
+* Owner: Moko Consulting
+* Version: 03.06.03
+* Status: Active
+* Effective Date: 2026-01-30
+* Classification: Public Open Source Documentation
+
+## Revision History
+
+| Date       | Change Summary                                        | Author          |
+| ---------- | ----------------------------------------------------- | --------------- |
+| 2026-01-30 | Updated metadata to MokoStandards format             | GitHub Copilot  |
+| 2025-01-04 | Initial Joomla development guide created             | GitHub Copilot  |