moko-platform/automation/push_files.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
 * DEFGROUP: MokoStandards.Automation
 * INGROUP: MokoStandards.Scripts
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 * PATH: /automation/push_files.php
 * BRIEF: Push one or more specific files to one or more remote repositories
 */

declare(strict_types=1);

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

use MokoEnterprise\{
    ApiClient,
    AuditLogger,
    CLIApp,
    Config,
    DefinitionParser,
    GitPlatformAdapter,
    MetricsCollector,
    PlatformAdapterFactory,
    ProjectTypeDetector
};

/**
 * Targeted File Push Tool
 *
 * Pushes one or more specific files from MokoStandards templates to one or
 * more remote repositories — without running a full sync.
 *
 * Files are specified by their destination path as they appear in the target
 * repository (e.g., ".github/ISSUE_TEMPLATE/config.yml").  The tool looks up
 * the matching source template from the appropriate platform definition.
 *
 * Files may also be given as "source:destination" pairs to bypass definition
 * lookup and push any arbitrary local file.
 *
 * Usage:
 *   php push_files.php --files=.github/ISSUE_TEMPLATE/config.yml --repos=MokoCRM
 *   php push_files.php --files=".github/workflows/ci.yml,.github/workflows/codeql-analysis.yml" --repos=MokoCRM,WaasComponent
 *   php push_files.php --files=templates/foo.txt:docs/foo.txt --repos=MyRepo --direct
 */
class PushFiles extends CLIApp
{
    public const DEFAULT_ORG = 'MokoConsulting';
    public const VERSION = '04.06.00';

    private ApiClient $api;
    private GitPlatformAdapter $adapter;
    private AuditLogger $logger;
    private DefinitionParser $defParser;
    private ProjectTypeDetector $typeDetector;

    /**
     * Setup command-line arguments
     */
    protected function setupArguments(): array
    {
        return [
            'org:'     => 'GitHub organization (default: ' . self::DEFAULT_ORG . ')',
            'repos:'   => 'Target repositories — comma or space-separated (required)',
            'files:'   => 'Files to push — destination paths or source:destination pairs, comma/space-separated (required)',
            'message:' => 'Custom commit message (optional)',
            'branch:'  => 'Target branch for direct pushes (default: repo default branch). Ignored unless --direct is set',
            'direct'   => 'Push directly to target branch instead of creating a PR',
            'yes'      => 'Auto-confirm without prompting',
            'no-issue' => 'Skip creating a tracking issue in each target repository',
        ];
    }

    /**
     * Main execution
     */
    protected function run(): int
    {
        $this->log('📦 MokoStandards File Push v' . self::VERSION, 'INFO');

        if (!$this->initializeComponents()) {
            return 1;
        }

        $org       = $this->getOption('org', self::DEFAULT_ORG);
        $reposArg  = $this->getOption('repos', '');
        $filesArg  = $this->getOption('files', '');
        $direct    = $this->hasOption('direct');
        $autoYes   = $this->hasOption('yes');

        // Validate required arguments
        if (empty($reposArg)) {
            $this->log('❌ --repos is required. Specify one or more repository names.', 'ERROR');
            $this->log('   Example: --repos=MokoCRM,WaasComponent', 'ERROR');
            return 1;
        }

        if (empty($filesArg)) {
            $this->log('❌ --files is required. Specify destination paths or source:destination pairs.', 'ERROR');
            $this->log('   Example: --files=.github/ISSUE_TEMPLATE/config.yml', 'ERROR');
            return 1;
        }

        $repos = $this->parseList($reposArg);
        $files = $this->parseList($filesArg);

        $this->log("Organisation: {$org}", 'INFO');
        $this->log('Repositories: ' . implode(', ', $repos), 'INFO');
        $this->log('Files:        ' . implode(', ', $files), 'INFO');
        $this->log('Mode:         ' . ($direct ? 'direct commit' : 'pull request'), 'INFO');

        // Resolve file mappings for each repo
        $this->log("\n🔍 Resolving file mappings...", 'INFO');
        $repoFileMaps = $this->buildRepoFileMaps($org, $repos, $files);

        if (empty($repoFileMaps)) {
            $this->log('❌ No files could be resolved. Check file paths and platform definitions.', 'ERROR');
            return 1;
        }

        // Confirm before proceeding
        if (!$autoYes && !$this->confirm($repoFileMaps, $direct)) {
            $this->log('❌ Cancelled.', 'INFO');
            return 0;
        }

        // Execute pushes
        $results = $this->executePushes($org, $repoFileMaps, $direct);

        $this->displayResults($results);

        if ($results['failed'] > 0 && !isset($this->options['no-issue']) && !$this->dryRun) {
            $this->createFailureIssue($org, $results);
        }

        return $results['failed'] > 0 ? 1 : 0;
    }

    /**
     * Initialize enterprise components
     */
    private function initializeComponents(): bool
    {
        $config = Config::load();

        try {
            $this->adapter      = PlatformAdapterFactory::create($config);
            $this->api          = $this->adapter->getApiClient();
            $this->logger       = new AuditLogger('push_files');
            $this->defParser    = new DefinitionParser();
            $this->typeDetector = new ProjectTypeDetector($this->logger);

            $platform = $this->adapter->getPlatformName();
            $this->log("✓ Components initialized for platform: {$platform}", 'INFO');
            return true;
        } catch (\Exception $e) {
            $this->log('❌ Failed to initialize: ' . $e->getMessage(), 'ERROR');
            return false;
        }
    }

    /**
     * Parse a comma- or space-separated list into a clean array
     */
    private function parseList(string $input): array
    {
        return array_values(array_filter(
            array_map('trim', preg_split('/[\s,]+/', $input)),
            fn($v) => $v !== ''
        ));
    }

    /**
     * Build per-repo file maps: repo → [ [source, destination], … ]
     *
     * Each entry in $files is either:
     *   - "destination/path"            → looked up in the platform definition
     *   - "source/path:destination/path" → used as-is (raw mode)
     *
     * @param  string[] $repos
     * @param  string[] $files
     * @return array<string, list<array{source: string, destination: string}>>
     */
    private function buildRepoFileMaps(string $org, array $repos, array $files): array
    {
        $repoRoot = dirname(__DIR__, 2);
        $maps     = [];

        foreach ($repos as $repo) {
            // Detect the repo's platform so we load the right definition
            $platform = $this->detectRepoPlatform($org, $repo);
            $this->log("  {$repo}: platform = {$platform}", 'INFO');

            // Build a destination→source lookup from the definition
            $defEntries   = $this->defParser->parseForPlatform($platform, $repoRoot);
            $destToSource = [];
            foreach ($defEntries as $entry) {
                $destToSource[$entry['destination']] = $entry['source'];
            }

            $resolved = [];
            foreach ($files as $fileSpec) {
                if (str_contains($fileSpec, ':')) {
                    // Raw source:destination pair
                    [$src, $dest] = explode(':', $fileSpec, 2);
                    $srcAbs = rtrim($repoRoot, '/') . '/' . ltrim($src, '/');
                    if (!file_exists($srcAbs)) {
                        $this->log("  ⚠️  Source not found for {$repo}: {$src}", 'WARN');
                        continue;
                    }
                    $resolved[] = ['source' => $srcAbs, 'destination' => $dest];
                    $this->log("    ✓ {$dest} (raw: {$src})", 'INFO');
                } else {
                    // Destination path — look up in definition
                    $dest = ltrim($fileSpec, '/');
                    if (isset($destToSource[$dest])) {
                        $src    = $destToSource[$dest];
                        $srcAbs = str_starts_with($src, '/')
                            ? $src
                            : rtrim($repoRoot, '/') . '/' . ltrim($src, '/');
                        if (!file_exists($srcAbs)) {
                            $this->log("  ⚠️  Template not found for {$repo}: {$src}", 'WARN');
                            continue;
                        }
                        $resolved[] = ['source' => $srcAbs, 'destination' => $dest];
                        $this->log("    ✓ {$dest}", 'INFO');
                    } else {
                        $this->log("  ⚠️  {$dest} not found in {$platform} definition for {$repo}", 'WARN');
                    }
                }
            }

            if (!empty($resolved)) {
                $maps[$repo] = $resolved;
            }
        }

        return $maps;
    }

    /**
     * Detect platform for a repo by checking its sync def file, falling back
     * to the live GitHub API detection used by bulk_sync.
     */
    private function detectRepoPlatform(string $org, string $repo): string
    {
        // Check local sync def first — fastest path
        $defDir = dirname(__DIR__) . '/definitions/sync';
        $defFile = "{$defDir}/{$repo}.def.tf";
        if (file_exists($defFile)) {
            $content = file_get_contents($defFile) ?: '';
            if (preg_match('/detected_platform\s*=\s*"([^"]+)"/', $content, $m)) {
                return $m[1];
            }
        }

        // Fall back to live detection
        try {
            $repoData = $this->api->get("/repos/{$org}/{$repo}");
            return $this->typeDetector->detect($repoData, $org, $repo);
        } catch (\Exception $e) {
            $this->log("  ⚠️  Could not detect platform for {$repo}, using 'default'", 'WARN');
            return 'default';
        }
    }

    /**
     * Prompt for confirmation before pushing
     *
     * @param array<string, list<array{source: string, destination: string}>> $repoFileMaps
     */
    private function confirm(array $repoFileMaps, bool $direct): bool
    {
        if ($this->quiet) {
            return true;
        }

        $totalFiles = array_sum(array_map('count', $repoFileMaps));
        $totalRepos = count($repoFileMaps);
        $mode       = $direct ? 'direct commit' : 'PR';

        echo "\n";
        foreach ($repoFileMaps as $repo => $entries) {
            echo "  {$repo}:\n";
            foreach ($entries as $entry) {
                echo "    → {$entry['destination']}\n";
            }
        }
        echo "\n";
        echo "⚠️  About to push {$totalFiles} file(s) to {$totalRepos} repo(s) via {$mode}.\n";
        echo "Continue? [y/N]: ";

        $handle = fopen('php://stdin', 'r');
        $line   = fgets($handle);
        if ($handle) {
            fclose($handle);
        }

        return is_string($line) && strtolower(trim($line)) === 'y';
    }

    /**
     * Execute all file pushes
     *
     * @param  array<string, list<array{source: string, destination: string}>> $repoFileMaps
     * @return array{total: int, success: int, failed: int, repos: array<string, string>}
     */
    private function executePushes(string $org, array $repoFileMaps, bool $direct): array
    {
        $results = [
            'total'   => count($repoFileMaps),
            'success' => 0,
            'failed'  => 0,
            'repos'   => [],
        ];

        $customMessage = $this->getOption('message', '');
        $targetBranch  = $this->getOption('branch', '');

        foreach ($repoFileMaps as $repo => $entries) {
            $this->log("\n[{$repo}] Pushing " . count($entries) . ' file(s)...', 'INFO');

            try {
                // Resolve the default branch
                $repoData      = $this->adapter->getRepo($org, $repo);
                $defaultBranch = $repoData['default_branch'] ?? 'main';
                $branch        = $direct
                    ? ($targetBranch ?: $defaultBranch)
                    : $this->createSyncBranch($org, $repo, $defaultBranch);

                $pushed = 0;
                foreach ($entries as $entry) {
                    if ($this->pushSingleFile($org, $repo, $entry['source'], $entry['destination'], $branch, $customMessage)) {
                        $pushed++;
                        $this->log("  ✓ {$entry['destination']}", 'INFO');
                    } else {
                        $this->log("  ✗ {$entry['destination']}", 'ERROR');
                    }
                }

                if ($pushed === 0) {
                    $results['failed']++;
                    $results['repos'][$repo] = 'failed';
                    continue;
                }

                $prNumber = null;
                if (!$direct) {
                    $prTitle  = "chore: push " . count($entries) . " file(s) from MokoStandards";
                    $prBody   = $this->buildPRBody($entries);
                    $pr       = $this->adapter->createPullRequest(
                        $org,
                        $repo,
                        $prTitle,
                        $branch,
                        $defaultBranch,
                        $prBody,
                        ['assignees' => ['jmiller']]
                    );
                    $prNumber = $pr['number'] ?? null;
                    $this->log("  📋 PR #{$prNumber} created", 'INFO');
                    $results['repos'][$repo] = "pr#{$prNumber}";
                } else {
                    $results['repos'][$repo] = 'pushed';
                }

                if (!isset($this->options['no-issue']) && !$this->dryRun) {
                    $this->createTargetRepoIssue($org, $repo, $entries, $prNumber, $direct ? $branch : null);
                }

                $results['success']++;
            } catch (\Exception $e) {
                $this->log("  ✗ {$repo}: " . $e->getMessage(), 'ERROR');
                $results['failed']++;
                $results['repos'][$repo] = 'failed';
            }
        }

        return $results;
    }

    /**
     * Create a uniquely-named sync branch off the default branch
     */
    private function createSyncBranch(string $org, string $repo, string $base): string
    {
        $branchName = 'moko/push-files-' . date('Ymd-His');

        // Resolve the base branch to a commit SHA using the adapter
        $sha = $this->adapter->resolveRef($org, $repo, $base);

        if (empty($sha)) {
            throw new \RuntimeException("Cannot resolve SHA for branch {$base} in {$repo}");
        }

        $this->api->post("/repos/{$org}/{$repo}/git/refs", [
            'ref' => "refs/heads/{$branchName}",
            'sha' => $sha,
        ]);

        $this->log("  🌿 Branch created: {$branchName}", 'INFO');
        return $branchName;
    }

    /**
     * Push a single file to a repository branch via the Contents API
     *
     * @return bool True on success
     */
    private function pushSingleFile(
        string $org,
        string $repo,
        string $sourcePath,
        string $destPath,
        string $branch,
        string $customMessage
    ): bool {
        $content = file_get_contents($sourcePath);
        if ($content === false) {
            $this->log("  ⚠️  Cannot read source: {$sourcePath}", 'WARN');
            return false;
        }

        $message = !empty($customMessage)
            ? $customMessage
            : "chore: update {$destPath} from MokoStandards";

        // Fetch existing file SHA (needed for updates)
        $existingSha = null;
        try {
            $existing    = $this->adapter->getFileContents($org, $repo, $destPath, $branch);
            $existingSha = $existing['sha'] ?? null;
        } catch (\Exception $e) {
            // File does not exist — create it (no sha needed)
            $this->adapter->getApiClient()->resetCircuitBreaker();
        }

        try {
            $this->adapter->createOrUpdateFile(
                $org,
                $repo,
                $destPath,
                $content,
                $message,
                $existingSha,
                $branch
            );
            return true;
        } catch (\Exception $e) {
            $this->log("  ✗ API error pushing {$destPath}: " . $e->getMessage(), 'ERROR');
            return false;
        }
    }

    /**
     * Create a tracking issue in the target repository after a successful push.
     *
     * @param list<array{source: string, destination: string}> $entries
     */
    private function createTargetRepoIssue(
        string $org,
        string $repo,
        array $entries,
        ?int $prNumber,
        ?string $directBranch
    ): void {
        $now     = gmdate('Y-m-d H:i:s') . ' UTC';
        $version = self::VERSION;
        $source  = $this->adapter->getRepoWebUrl($org, 'MokoStandards');

        $title = "chore: MokoStandards file push tracking";

        $deliveryLine = $prNumber !== null
            ? "| **Pull request** | [#{$prNumber}](" . $this->adapter->getPullRequestWebUrl($org, $repo, $prNumber) . ") |"
            : "| **Delivery** | Direct commit to `{$directBranch}` |";

        $fileRows = implode("\n", array_map(
            fn($e) => "- `{$e['destination']}`",
            $entries
        ));

        $body = <<<MD
        ## MokoStandards File Push

        One or more files were pushed to this repository from MokoStandards.

        | Field | Value |
        |-------|-------|
        | **Pushed** | {$now} |
        | **Standards version** | `{$version}` |
        {$deliveryLine}
        | **Source** | [{$source}]({$source}) |

        ### Files pushed

        {$fileRows}

        ---
        *Generated automatically by [MokoStandards]({$source}) `push_files.php`*
        MD;

        $body = preg_replace('/^        /m', '', $body);

        $labels = ['standards-update', 'mokostandards', 'type: chore', 'automation'];

        try {
            $existing = $this->api->get("/repos/{$org}/{$repo}/issues", [
                'labels'    => 'standards-update',
                'state'     => 'all',
                'per_page'  => 1,
                'sort'      => 'created',
                'direction' => 'desc',
            ]);

            if (!empty($existing) && isset($existing[0]['number'])) {
                $num   = $existing[0]['number'];
                $patch = ['title' => $title, 'body' => $body, 'assignees' => ['jmiller']];
                if (($existing[0]['state'] ?? 'open') === 'closed') {
                    $patch['state'] = 'open';
                }
                $this->api->patch("/repos/{$org}/{$repo}/issues/{$num}", $patch);
                try {
                    $this->api->post("/repos/{$org}/{$repo}/issues/{$num}/labels", ['labels' => $labels]);
                } catch (\Exception $le) {
/* non-fatal */
                }
                $this->log("  📋 Tracking issue #{$num} updated in {$repo}", 'INFO');
            } else {
                $issue = $this->api->post("/repos/{$org}/{$repo}/issues", [
                    'title'     => $title,
                    'body'      => $body,
                    'labels'    => $labels,
                    'assignees' => ['jmiller'],
                ]);
                $num = $issue['number'] ?? null;
                $this->log("  📋 Tracking issue #{$num} created in {$repo}", 'INFO');
            }

            // Cross-link: patch the sync PR body to reference the tracking issue
            // so GitHub shows it in the PR's Development sidebar.
            if ($prNumber !== null && is_int($num)) {
                try {
                    $pr          = $this->api->get("/repos/{$org}/{$repo}/pulls/{$prNumber}");
                    $currentBody = $pr['body'] ?? '';
                    $ref         = "Linked to #{$num}";
                    if (!str_contains($currentBody, $ref)) {
                        $this->api->patch("/repos/{$org}/{$repo}/pulls/{$prNumber}", [
                            'body' => $ref . "\n\n" . $currentBody,
                        ]);
                    }
                } catch (\Exception $le) {
/* non-fatal */
                }
            }
        } catch (\Exception $e) {
            $this->log("  ⚠️  Could not create/update tracking issue in {$repo}: " . $e->getMessage(), 'WARN');
        }
    }

    /**
     * Create or update a failure issue in MokoStandards when repos fail to receive files.
     * Uses the 'push-failure' label. Reopens a closed issue rather than creating a duplicate.
     */
    private function createFailureIssue(string $org, array $results): void
    {
        $now     = gmdate('Y-m-d H:i:s') . ' UTC';
        $failed  = $results['failed'];
        $version = self::VERSION;

        $failedRepos = array_keys(array_filter(
            $results['repos'] ?? [],
            fn($s) => $s === 'failed'
        ));

        $repoList = implode("\n", array_map(fn($r) => "- `{$r}`", $failedRepos));
        $fileArgs = $this->getOption('files', '');

        $title = "fix: push_files failed for {$failed} repo(s) — action required";

        $body = <<<MD
        ## File Push Failure

        `push_files.php` v{$version} encountered failures pushing files on {$now}.

        ### Failed repositories

        {$repoList}

        ### Files that were being pushed

        ```
        {$fileArgs}
        ```

        ### Next steps

        1. Check the output above for the specific error per repo.
        2. Fix the underlying issue (API token, branch permissions, file path, etc.).
        3. Re-run: `php automation/push_files.php --org={$org} --repos=<repo> --files=<files> --yes`
        4. Close this issue once resolved.

        ---
        *Auto-created by `push_files.php` — close once resolved.*
        MD;

        $body = preg_replace('/^        /m', '', $body);

        try {
            $existing = $this->api->get("/repos/{$org}/MokoStandards/issues", [
                'labels'    => 'push-failure',
                'state'     => 'all',
                'per_page'  => 1,
                'sort'      => 'created',
                'direction' => 'desc',
            ]);

            if (!empty($existing) && isset($existing[0]['number'])) {
                $num   = $existing[0]['number'];
                $patch = ['title' => $title, 'body' => $body, 'assignees' => ['jmiller']];
                if (($existing[0]['state'] ?? 'open') === 'closed') {
                    $patch['state'] = 'open';
                }
                $this->api->patch("/repos/{$org}/MokoStandards/issues/{$num}", $patch);
                $this->log("🚨 Failure issue #{$num} updated: {$org}/MokoStandards#{$num}", 'WARN');
            } else {
                $issue = $this->api->post("/repos/{$org}/MokoStandards/issues", [
                    'title'     => $title,
                    'body'      => $body,
                    'labels'    => ['push-failure'],
                    'assignees' => ['jmiller'],
                ]);
                $num = $issue['number'] ?? '?';
                $this->log("🚨 Failure issue created: {$org}/MokoStandards#{$num}", 'WARN');
            }
        } catch (\Exception $e) {
            $this->log("⚠️  Could not create/update failure issue: " . $e->getMessage(), 'WARN');
        }
    }

    /**
     * Build a markdown PR body listing every pushed file
     *
     * @param list<array{source: string, destination: string}> $entries
     */
    private function buildPRBody(array $entries): string
    {
        $now   = gmdate('Y-m-d H:i:s') . ' UTC';
        $lines = ["## MokoStandards File Push\n", "**Pushed:** {$now}\n", '### Files\n'];

        foreach ($entries as $entry) {
            $lines[] = "- `{$entry['destination']}`";
        }

        $sourceUrl = $this->adapter->getRepoWebUrl(self::DEFAULT_ORG, 'MokoStandards');
        $lines[] = "\n---\n*Generated by [MokoStandards]({$sourceUrl}) `push_files.php`*";

        return implode("\n", $lines);
    }

    /**
     * Display final results
     *
     * @param array{total: int, success: int, failed: int, repos: array<string, string>} $results
     */
    private function displayResults(array $results): void
    {
        $this->log("\n" . str_repeat('=', 60), 'INFO');
        $this->log('📊 Push Complete', 'INFO');
        $this->log(str_repeat('=', 60), 'INFO');
        $this->log(sprintf('Total:   %d repos', $results['total']), 'INFO');
        $this->log(sprintf('Success: %d', $results['success']), 'INFO');
        $this->log(sprintf('Failed:  %d', $results['failed']), 'INFO');

        if ($this->verbose) {
            $this->log("\n📋 Details:", 'INFO');
            foreach ($results['repos'] as $repo => $outcome) {
                $icon = str_starts_with($outcome, 'pr#') || $outcome === 'pushed' ? '✓' : '✗';
                $this->log("  {$icon} {$repo}: {$outcome}", 'INFO');
            }
        }

        $this->log(str_repeat('=', 60), 'INFO');
    }
}

// Execute if run directly
if (php_sapi_name() === 'cli' && isset($argv[0]) && realpath($argv[0]) === __FILE__) {
    $app = new PushFiles(
        'push-files',
        'Push one or more specific files to one or more remote repositories',
        PushFiles::VERSION
    );
    exit($app->execute());
}