MokoCLI/deploy/deploy-joomla.php

#!/usr/bin/env php
<?php

/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 *
 * This file is part of a Moko Consulting project.
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * FILE INFORMATION
<<<<<<< HEAD
 * DEFGROUP: MokoCLI.Scripts.Deploy
 * INGROUP: MokoCLI
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
=======
 * DEFGROUP: MokoPlatform.Scripts.Deploy
 * INGROUP: MokoPlatform
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
>>>>>>> main
 * PATH: /deploy/deploy-joomla.php
 * BRIEF: Smart Joomla deploy — routes files to correct Joomla directories based on XML manifest
 *
 * Parses the extension's XML manifest to determine type (component, module,
 * plugin, template, library, package) and deploys each section directly to
 * its correct location on the Joomla server. No reinstall needed for code
 * changes — only XML manifest changes require a Joomla reinstall.
 *
 * USAGE
 *   php deploy/deploy-joomla.php --path . --config /tmp/sftp-config.json
 *   php deploy/deploy-joomla.php --path . --config /tmp/sftp-config.json --dry-run
 *   php deploy/deploy-joomla.php --path . --env dev
 */

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';
require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';

use MokoCli\CliFramework;
use phpseclib3\Net\SFTP;
use phpseclib3\Crypt\PublicKeyLoader;

/**
 * Joomla-aware SFTP deployment.
 *
 * Reads the extension XML manifest to determine:
 *   - Extension type (component, module, plugin, template, library)
 *   - Element name (com_xxx, mod_xxx, plg_group_name, tpl_xxx)
 *   - Client (site or administrator)
 *   - Plugin group (system, content, etc.)
 *
 * Then maps src/ subdirectories to their correct Joomla server paths:
 *
 *   Component:
 *     src/admin/      -> administrator/components/{element}/
 *     src/site/       -> components/{element}/
 *     src/media/      -> media/{element}/
 *     src/api/        -> api/components/{element}/
 *
 *   Module:
 *     src/            -> modules/{element}/ (site) or administrator/modules/{element}/ (admin)
 *     src/media/      -> media/{element}/
 *
 *   Plugin:
 *     src/            -> plugins/{group}/{name}/
 *     src/media/      -> media/{element}/
 *
 *   Template:
 *     src/            -> templates/{name}/ (site) or administrator/templates/{name}/ (admin)
 *     src/media/      -> media/templates/site/{name}/ or media/templates/administrator/{name}/
 *
 *   Library:
 *     src/            -> libraries/{name}/
 *     src/media/      -> media/{element}/
 */
class DeployJoomlaCli extends CliFramework
{
    private string $repoPath = '.';
    private string $srcDir = 'src';
    private array $config = [];
    private int $uploaded = 0;
    private int $unchanged = 0;
    private int $skipped = 0;
    private int $deleted = 0;
    private array $ignorePatterns = [];

    protected function configure(): void
    {
        $this->setDescription('Smart Joomla deploy — routes files to correct Joomla directories based on XML manifest');
        $this->addArgument('--path', 'Repository root path', '.');
        $this->addArgument('--src-dir', 'Source directory relative to path', 'src');
        $this->addArgument('--config', 'Path to sftp-config.json', '');
        $this->addArgument('--key-passphrase', 'SSH key passphrase', '');
    }

    protected function run(): int
    {
        $this->repoPath = $this->getArgument('--path');
        $this->srcDir = $this->getArgument('--src-dir');
        $configPath = $this->getArgument('--config');
        $keyPassphrase = $this->getArgument('--key-passphrase');

        if ($keyPassphrase !== '') {
            $this->config['key_passphrase'] = $keyPassphrase;
        }

        $this->repoPath = realpath($this->repoPath) ?: $this->repoPath;

        // Resolve src dir
        if (!str_starts_with($this->srcDir, '/')) {
            $this->srcDir = "{$this->repoPath}/{$this->srcDir}";
        }
        // Try htdocs/ as fallback
        if (!is_dir($this->srcDir) && is_dir("{$this->repoPath}/htdocs")) {
            $this->srcDir = "{$this->repoPath}/htdocs";
        }

        // Load config
        if ($configPath !== '' && file_exists($configPath)) {
            $json = file_get_contents($configPath);
            $json = preg_replace('#^\s*//.*$#m', '', $json);
            $json = preg_replace('#,\s*([\]}])#', '$1', $json);
            $parsed = json_decode($json, true);
            if (is_array($parsed)) {
                $this->config = array_merge($this->config, $parsed);
            }
        }

        $manifest = $this->findManifest();
        if ($manifest === null) {
            $this->log('ERROR', "No Joomla XML manifest found in {$this->srcDir}");
            return 1;
        }

        $ext = $this->parseManifest($manifest);
        if ($ext === null) {
            $this->log('ERROR', "Failed to parse manifest: {$manifest}");
            return 1;
        }

        $this->log('INFO', "Extension: {$ext['type']} / {$ext['element']} (client: {$ext['client']})");

        $deployMap = $this->buildDeployMap($ext);
        if (empty($deployMap)) {
            $this->log('ERROR', "No deploy mappings for extension type: {$ext['type']}");
            return 1;
        }

        $this->log('INFO', "Deploy mappings:");
        foreach ($deployMap as $map) {
            $this->log('INFO', "  {$map['local']} -> {$map['remote']}");
        }

        // Load ignore patterns
        $this->ignorePatterns = $this->loadFtpIgnore();

        // Check if manifest changed (warn user about reinstall)
        $this->checkManifestChange($ext, $manifest);

        if ($this->dryRun) {
            $this->log('INFO', "[DRY RUN] Would deploy " . count($deployMap) . " mappings");
            foreach ($deployMap as $map) {
                if (is_dir($map['local'])) {
                    $count = iterator_count(
                        new \RecursiveIteratorIterator(
                            new \RecursiveDirectoryIterator($map['local'], \FilesystemIterator::SKIP_DOTS)
                        )
                    );
                    $this->log('INFO', "  {$map['local']} ({$count} files) -> {$map['remote']}");
                }
            }
            return 0;
        }

        // Connect
        $sftp = $this->connectSftp();
        if ($sftp === null) {
            return 1;
        }

        // Deploy each mapping
        $errors = 0;
        foreach ($deployMap as $map) {
            if (!is_dir($map['local'])) {
                if ($this->verbose) {
                    $this->log('INFO', "  SKIP: {$map['local']} (directory not found)");
                }
                continue;
            }

            // Ensure remote directory exists
            $stat = @$sftp->stat($map['remote']);
            if ($stat === false) {
                $this->log('INFO', "  MKDIR: {$map['remote']}");
                $sftp->mkdir($map['remote'], -1, true);
            }

            $result = $this->uploadDirectory($sftp, $map['local'], $map['remote']);
            if ($result !== 0) {
                $errors++;
            }
        }

        // Also deploy the manifest file itself to the admin component directory
        if ($ext['type'] === 'component' && file_exists($manifest)) {
            $adminRemote = $this->getRemotePath($ext, 'admin');
            $manifestName = basename($manifest);
            $remoteDest = "{$adminRemote}/{$manifestName}";
            $this->uploadFile($sftp, $manifest, $remoteDest);
            $this->log('INFO', "  Manifest: {$manifestName} -> {$remoteDest}");
        }

        $this->log('INFO', "Done. Uploaded: {$this->uploaded}, Unchanged: {$this->unchanged}, Skipped: {$this->skipped}");

        return $errors > 0 ? 1 : 0;
    }

    /**
     * Find the Joomla XML manifest file.
     */
    private function findManifest(): ?string
    {
        $searchDirs = [$this->srcDir, $this->repoPath];
        foreach ($searchDirs as $dir) {
            $iterator = new \DirectoryIterator($dir);
            foreach ($iterator as $file) {
                if ($file->isFile() && $file->getExtension() === 'xml') {
                    $content = file_get_contents($file->getPathname());
                    if ($content !== false && str_contains($content, '<extension')) {
                        return $file->getPathname();
                    }
                }
            }
            // Also check one level deep
            foreach (new \DirectoryIterator($dir) as $subdir) {
                if ($subdir->isDir() && !$subdir->isDot()) {
                    foreach (new \DirectoryIterator($subdir->getPathname()) as $file) {
                        if ($file->isFile() && $file->getExtension() === 'xml') {
                            $content = file_get_contents($file->getPathname());
                            if ($content !== false && str_contains($content, '<extension')) {
                                return $file->getPathname();
                            }
                        }
                    }
                }
            }
        }
        return null;
    }

    /**
     * Parse extension metadata from the XML manifest.
     *
     * @return array{type: string, element: string, client: string, group: string, name: string}|null
     */
    private function parseManifest(string $path): ?array
    {
        $xml = @simplexml_load_file($path);
        if ($xml === false || $xml->getName() !== 'extension') {
            return null;
        }

        $type    = (string) ($xml['type'] ?? 'component');
        $client  = (string) ($xml['client'] ?? 'site');
        $group   = (string) ($xml['group'] ?? '');
        $element = (string) ($xml->element ?? '');
        $name    = (string) ($xml->name ?? '');

        // Derive element from type + name if not explicit
        if (empty($element)) {
            $cleanName = strtolower(preg_replace('/[^a-zA-Z0-9_]/', '', $name));
            $element = match ($type) {
                'component' => "com_{$cleanName}",
                'module'    => "mod_{$cleanName}",
                'plugin'    => "plg_{$group}_{$cleanName}",
                'template'  => "tpl_{$cleanName}",
                'library'   => "lib_{$cleanName}",
                default     => $cleanName,
            };
        }

        // For plugins, derive the short name (without plg_group_ prefix)
        $shortName = $element;
        if ($type === 'plugin' && preg_match('/^plg_\w+_(.+)$/', $element, $m)) {
            $shortName = $m[1];
        } elseif ($type === 'template' && preg_match('/^tpl_(.+)$/', $element, $m)) {
            $shortName = $m[1];
        }

        return [
            'type'      => $type,
            'element'   => $element,
            'client'    => $client,
            'group'     => $group,
            'name'      => $name,
            'shortName' => $shortName,
        ];
    }

    /**
     * Build the local->remote deploy mapping based on extension type.
     *
     * @return array<int, array{local: string, remote: string}>
     */
    private function buildDeployMap(array $ext): array
    {
        $remotePath = rtrim((string) $this->config['remote_path'], '/');
        $src        = $this->srcDir;
        $map        = [];

        switch ($ext['type']) {
            case 'component':
                // Admin files
                if (is_dir("{$src}/admin") || is_dir("{$src}/administrator")) {
                    $adminLocal = is_dir("{$src}/admin") ? "{$src}/admin" : "{$src}/administrator";
                    $map[] = ['local' => $adminLocal, 'remote' => "{$remotePath}/administrator/components/{$ext['element']}"];
                }
                // Site files
                if (is_dir("{$src}/site")) {
                    $map[] = ['local' => "{$src}/site", 'remote' => "{$remotePath}/components/{$ext['element']}"];
                }
                // Media files
                if (is_dir("{$src}/media")) {
                    $map[] = ['local' => "{$src}/media", 'remote' => "{$remotePath}/media/{$ext['element']}"];
                }
                // API files (Joomla 4+)
                if (is_dir("{$src}/api")) {
                    $map[] = ['local' => "{$src}/api", 'remote' => "{$remotePath}/api/components/{$ext['element']}"];
                }
                // Language files (admin)
                if (is_dir("{$src}/language/admin") || is_dir("{$src}/admin/language")) {
                    $langDir = is_dir("{$src}/language/admin") ? "{$src}/language/admin" : "{$src}/admin/language";
                    $map[] = ['local' => $langDir, 'remote' => "{$remotePath}/administrator/language"];
                }
                // Language files (site)
                if (is_dir("{$src}/language/site") || is_dir("{$src}/site/language")) {
                    $langDir = is_dir("{$src}/language/site") ? "{$src}/language/site" : "{$src}/site/language";
                    $map[] = ['local' => $langDir, 'remote' => "{$remotePath}/language"];
                }
                break;

            case 'module':
                $base = $ext['client'] === 'administrator'
                    ? "{$remotePath}/administrator/modules/{$ext['element']}"
                    : "{$remotePath}/modules/{$ext['element']}";
                $map[] = ['local' => $src, 'remote' => $base];
                if (is_dir("{$src}/media")) {
                    $map[] = ['local' => "{$src}/media", 'remote' => "{$remotePath}/media/{$ext['element']}"];
                }
                break;

            case 'plugin':
                $map[] = ['local' => $src, 'remote' => "{$remotePath}/plugins/{$ext['group']}/{$ext['shortName']}"];
                if (is_dir("{$src}/media")) {
                    $map[] = ['local' => "{$src}/media", 'remote' => "{$remotePath}/media/{$ext['element']}"];
                }
                break;

            case 'template':
                $clientDir = $ext['client'] === 'administrator' ? 'administrator/' : '';
                $map[] = ['local' => $src, 'remote' => "{$remotePath}/{$clientDir}templates/{$ext['shortName']}"];
                if (is_dir("{$src}/media")) {
                    $mediaClient = $ext['client'] === 'administrator' ? 'administrator' : 'site';
                    $map[] = ['local' => "{$src}/media", 'remote' => "{$remotePath}/media/templates/{$mediaClient}/{$ext['shortName']}"];
                }
                break;

            case 'library':
                $map[] = ['local' => $src, 'remote' => "{$remotePath}/libraries/{$ext['shortName']}"];
                if (is_dir("{$src}/media")) {
                    $map[] = ['local' => "{$src}/media", 'remote' => "{$remotePath}/media/{$ext['element']}"];
                }
                break;

            case 'package':
                // Packages deploy their sub-extensions individually
                // For now, deploy to administrator/manifests/packages/
                $map[] = ['local' => $src, 'remote' => "{$remotePath}/administrator/manifests/packages"];
                break;
        }

        return $map;
    }

    /**
     * Get the remote path for a specific section of the extension.
     */
    private function getRemotePath(array $ext, string $section): string
    {
        $remotePath = rtrim((string) $this->config['remote_path'], '/');
        return match ($section) {
            'admin' => "{$remotePath}/administrator/components/{$ext['element']}",
            'site'  => "{$remotePath}/components/{$ext['element']}",
            'media' => "{$remotePath}/media/{$ext['element']}",
            default => $remotePath,
        };
    }

    /**
     * Check if the XML manifest has changed and warn about reinstall.
     */
    private function checkManifestChange(array $ext, string $manifestPath): void
    {
        $manifestName = basename($manifestPath);
        $this->log('INFO', '');
        $this->log('INFO', "NOTE: If {$manifestName} has changed (new fields, permissions, menu items,");
        $this->log('INFO', '      database schema), you must reinstall the extension through Joomla.');
        $this->log('INFO', '      Code changes (PHP, JS, CSS, language) do NOT require reinstall.');
        $this->log('INFO', '');
    }

    /**
     * Upload a directory recursively to the remote server.
     */
    private function uploadDirectory(SFTP $sftp, string $localDir, string $remoteDir): int
    {
        $errors = 0;
        $iterator = new \RecursiveIteratorIterator(
            new \RecursiveDirectoryIterator($localDir, \FilesystemIterator::SKIP_DOTS),
            \RecursiveIteratorIterator::SELF_FIRST
        );

        foreach ($iterator as $item) {
            $relativePath = substr($item->getPathname(), strlen($localDir) + 1);
            $relativePath = str_replace('\\', '/', $relativePath);
            $remotePath   = "{$remoteDir}/{$relativePath}";

            // Check ignore patterns
            if ($this->shouldIgnore($relativePath)) {
                $this->skipped++;
                continue;
            }

            if ($item->isDir()) {
                $stat = @$sftp->stat($remotePath);
                if ($stat === false) {
                    $sftp->mkdir($remotePath, -1, true);
                }
            } else {
                $result = $this->uploadFile($sftp, $item->getPathname(), $remotePath);
                if (!$result) {
                    $errors++;
                }
            }
        }

        return $errors;
    }

    /**
     * Upload a single file with smart diff (skip if unchanged).
     */
    private function uploadFile(SFTP $sftp, string $localPath, string $remotePath): bool
    {
        $localSize = filesize($localPath);
        $remoteStat = @$sftp->stat($remotePath);

        // Smart diff: skip if same size and hash
        if ($remoteStat !== false && ($remoteStat['size'] ?? -1) === $localSize) {
            $remoteContent = @$sftp->get($remotePath);
            if ($remoteContent !== false && md5($remoteContent) === md5_file($localPath)) {
                $this->unchanged++;
                return true;
            }
        }

        // Ensure parent directory exists
        $parentDir = dirname($remotePath);
        $parentStat = @$sftp->stat($parentDir);
        if ($parentStat === false) {
            $sftp->mkdir($parentDir, -1, true);
        }

        $result = $sftp->put($remotePath, $localPath, SFTP::SOURCE_LOCAL_FILE);
        if ($result) {
            $this->uploaded++;
            if ($this->verbose) {
                $this->log('INFO', "  UPLOAD: {$remotePath}");
            }
        } else {
            $this->log('ERROR', "  FAIL: {$remotePath}");
        }
        return $result;
    }

    /**
     * Check if a relative path should be ignored.
     */
    private function shouldIgnore(string $relativePath): bool
    {
        foreach ($this->ignorePatterns as $pattern) {
            if (preg_match($pattern, $relativePath)) {
                return true;
            }
        }
        // Always skip dotfiles and common non-deploy files
        $basename = basename($relativePath);
        if (str_starts_with($basename, '.') && $basename !== '.htaccess') {
            return true;
        }
        return false;
    }

    /**
     * Load .ftpignore patterns.
     *
     * @return string[] Regex patterns
     */
    private function loadFtpIgnore(): array
    {
        $patterns = [];
        foreach ([$this->srcDir, $this->repoPath] as $dir) {
            $file = "{$dir}/.ftpignore";
            if (!file_exists($file)) {
                continue;
            }
            foreach (file($file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) as $line) {
                $line = trim($line);
                if ($line === '' || str_starts_with($line, '#')) {
                    continue;
                }
                // Convert glob to regex
                $regex = str_replace(['.', '*', '?'], ['\\.', '.*', '.'], $line);
                $patterns[] = "#^{$regex}(/|$)#i";
            }
        }
        return $patterns;
    }

    /**
     * Connect to the SFTP server.
     */
    private function connectSftp(): ?SFTP
    {
        $host = (string) $this->config['host'];
        $port = (int) ($this->config['port'] ?? 22);
        $user = (string) $this->config['user'];

        $this->log('INFO', "Connecting to {$user}@{$host}:{$port}...");

        $sftp = new SFTP($host, $port, 30);

        // Try key auth first
        if (!empty($this->config['ssh_key_file'])) {
            $keyPath = $this->config['ssh_key_file'];
            if (!file_exists($keyPath)) {
                $keyPath = "{$this->repoPath}/scripts/keys/{$keyPath}";
            }
            if (file_exists($keyPath)) {
                $passphrase = $this->config['key_passphrase'] ?? '';
                $key = PublicKeyLoader::load(file_get_contents($keyPath), $passphrase);
                if ($sftp->login($user, $key)) {
                    $this->log('INFO', 'Connected via SSH key');
                    return $sftp;
                }
                $this->warning('Key auth failed');
            }
        }

        // Fallback to password
        if (!empty($this->config['password'])) {
            if ($sftp->login($user, $this->config['password'])) {
                $this->log('INFO', 'Connected via password');
                return $sftp;
            }
        }

        $this->log('ERROR', 'Authentication failed');
        return null;
    }
}

$app = new DeployJoomlaCli();
exit($app->execute());