moko-platform/lib/Common.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.Lib
 * INGROUP: MokoStandards
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 * PATH: /lib/Common.php
 * BRIEF: Common utility functions for scripts
 * NOTE: Version format used throughout is zero-padded semver: XX.YY.ZZ (e.g. 04.00.04).
 *       All version regex patterns enforce exactly two digits per component by design.
 */

declare(strict_types=1);

/**
 * Common utility class for Moko Consulting scripts.
 *
 * Provides static helpers for logging, git introspection, and guards.
 */
class Common
{
    /**
     * Fallback version used when README.md cannot be parsed.
     * NOTE: Kept in sync with _FALLBACK_VERSION in the original common.sh.
     *       Update this constant when the minimum supported baseline version changes.
     */
    const FALLBACK_VERSION = '04.00.00';

    const REPO_URL  = 'https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API';
    const REPO_URL_GITHUB = 'https://git.mokoconsulting.tech/MokoConsulting/MokoStandards';
    const COPYRIGHT = 'Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>';
    const LICENSE   = 'GPL-3.0-or-later';

    // Exit codes
    const EXIT_SUCCESS      = 0;
    const EXIT_ERROR        = 1;
    const EXIT_INVALID_ARGS = 2;
    const EXIT_NOT_FOUND    = 3;
    const EXIT_PERMISSION   = 4;

    // ── Logging ───────────────────────────────────────────────────────────────

    /**
     * Print an informational message.
     *
     * @param string $message  Text to display.
     */
    public static function info(string $message): void
    {
        echo 'ℹ️  ' . $message . "\n";
    }

    /**
     * Print a success message.
     *
     * @param string $message  Text to display.
     */
    public static function success(string $message): void
    {
        echo '✅ ' . $message . "\n";
    }

    /**
     * Print a warning message.
     *
     * @param string $message  Text to display.
     */
    public static function warn(string $message): void
    {
        echo '⚠️  ' . $message . "\n";
    }

    /**
     * Print an error message to STDERR.
     *
     * @param string $message  Error text.
     */
    public static function error(string $message): void
    {
        fwrite(STDERR, '❌ ' . $message . "\n");
    }

    /**
     * Print a fatal error to STDERR and exit.
     *
     * @param string $message   Error text.
     * @param int    $exitCode  One of the EXIT_* constants.
     * @return never
     */
    public static function fatal(string $message, int $exitCode = self::EXIT_ERROR): never
    {
        fwrite(STDERR, '❌ ' . $message . "\n");
        exit($exitCode);
    }

    /**
     * Print a debug message to STDERR when the DEBUG env var is set.
     *
     * @param string $message  Debug text.
     */
    public static function debug(string $message): void
    {
        if (!empty($_SERVER['DEBUG'] ?? getenv('DEBUG'))) {
            fwrite(STDERR, '🔍 ' . $message . "\n");
        }
    }

    /**
     * Print a plain message to stdout.
     *
     * @param string $message  Text to display.
     */
    public static function plain(string $message): void
    {
        echo $message . "\n";
    }

    // ── Guards ────────────────────────────────────────────────────────────────

    /**
     * Abort if a command is not available on PATH.
     *
     * @param string $cmd         Command name (e.g. 'git').
     * @param string $description Human-readable description for the error message.
     */
    public static function requireCommand(string $cmd, string $description = ''): void
    {
        $which = trim((string) shell_exec('command -v ' . escapeshellarg($cmd) . ' 2>/dev/null'));
        if ($which === '') {
            $msg = $description !== '' ? $description : "Command required: {$cmd}";
            self::fatal($msg, self::EXIT_NOT_FOUND);
        }
    }

    /**
     * Abort if a file does not exist.
     *
     * @param string $path        Absolute or relative file path.
     * @param string $description Human-readable label used in the error message.
     */
    public static function requireFile(string $path, string $description = 'File'): void
    {
        if (!is_file($path)) {
            self::fatal("{$description} not found: {$path}", self::EXIT_NOT_FOUND);
        }
    }

    /**
     * Abort if a directory does not exist.
     *
     * @param string $path        Absolute or relative directory path.
     * @param string $description Human-readable label used in the error message.
     */
    public static function requireDir(string $path, string $description = 'Directory'): void
    {
        if (!is_dir($path)) {
            self::fatal("{$description} not found: {$path}", self::EXIT_NOT_FOUND);
        }
    }

    // ── Repository utilities ──────────────────────────────────────────────────

    /**
     * Return the absolute path to the repository root by walking up from cwd.
     *
     * @throws \RuntimeException  When no .git directory is found.
     * @return string  Absolute path (no trailing slash).
     */
    public static function getRepoRoot(): string
    {
        $dir = (string) getcwd();
        while ($dir !== '/') {
            if (is_dir($dir . '/.git')) {
                return $dir;
            }
            $dir = dirname($dir);
        }
        self::fatal('Not in a git repository', self::EXIT_ERROR);
    }

    /**
     * Return the current git branch name (or "unknown").
     *
     * @return string  Branch name.
     */
    public static function getGitBranch(): string
    {
        $branch = trim((string) shell_exec('git rev-parse --abbrev-ref HEAD 2>/dev/null'));
        return $branch !== '' ? $branch : 'unknown';
    }

    /**
     * Return the current full git commit hash (or "unknown").
     *
     * @return string  Full commit SHA.
     */
    public static function getGitCommit(): string
    {
        $hash = trim((string) shell_exec('git rev-parse HEAD 2>/dev/null'));
        return $hash !== '' ? $hash : 'unknown';
    }

    /**
     * Return the short git commit hash (or "unknown").
     *
     * @return string  Short commit SHA.
     */
    public static function getGitCommitShort(): string
    {
        $hash = trim((string) shell_exec('git rev-parse --short HEAD 2>/dev/null'));
        return $hash !== '' ? $hash : 'unknown';
    }

    /**
     * Return true when the git working directory is clean.
     *
     * @return bool  True if no uncommitted changes.
     */
    public static function isGitClean(): bool
    {
        return trim((string) shell_exec('git status --porcelain 2>/dev/null')) === '';
    }

    /**
     * Return true when the current directory is inside a git repository.
     *
     * @return bool  True if inside a git repo.
     */
    public static function isGitRepo(): bool
    {
        exec('git rev-parse --git-dir 2>/dev/null', $out, $code);
        return $code === 0;
    }

    // ── Path utilities ────────────────────────────────────────────────────────

    /**
     * Return the path relative to the repository root, prefixed with '/'.
     *
     * @param string $absolutePath  Absolute filesystem path.
     * @return string  Repo-relative path starting with '/'.
     */
    public static function getRelativePath(string $absolutePath): string
    {
        $root = self::getRepoRoot();
        $rel  = str_starts_with($absolutePath, $root)
            ? substr($absolutePath, strlen($root))
            : $absolutePath;
        return '/' . ltrim($rel, '/');
    }

    /**
     * Create a directory (and parents) if it does not already exist.
     *
     * @param string $path        Directory path to ensure.
     * @param string $description Human-readable label for log output.
     */
    public static function ensureDir(string $path, string $description = 'Directory'): void
    {
        if (!is_dir($path)) {
            mkdir($path, 0755, true);
            self::info("Created {$description}: {$path}");
        }
    }

    // ── Version helpers ───────────────────────────────────────────────────────

    /**
     * Read the VERSION from the FILE INFORMATION block in README.md.
     *
     * Searches upward from cwd for the repo root, then reads README.md.
     * Falls back to FALLBACK_VERSION when the file is absent or unparseable.
     *
     * @return string  Zero-padded semver string, e.g. "04.00.04".
     */
    public static function getVersionFromReadme(): string
    {
        try {
            $root   = self::getRepoRoot();
            $readme = $root . '/README.md';
            if (!is_file($readme)) {
                return self::FALLBACK_VERSION;
            }
            $content = file_get_contents($readme);
            if (preg_match('/^\s*VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', (string) $content, $m)) {
                return $m[1];
            }
        } catch (\Throwable $e) {
            // Fall through to fallback
        }
        return self::FALLBACK_VERSION;
    }
}