MokoCLI/lib/CliBase.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.Lib
 * INGROUP: MokoCLI
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
=======
 * DEFGROUP: MokoPlatform.Lib
 * INGROUP: MokoPlatform
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
>>>>>>> main
 * PATH: /lib/CliBase.php
 * BRIEF: Standalone base CLI class for scripts that do not use CliFramework
 */

declare(strict_types=1);

/**
 * Base CLI Application Class
 *
 * Provides common functionality for command-line scripts that do not
 * require the full CliFramework enterprise stack.
 */
abstract class CliBase
{
    protected array $args = [];
    protected array $options = [];
    protected bool $verbose = false;
    protected bool $dryRun = false;
    protected string $scriptName;

    /**
     * @param array<int,string> $argv  Command-line argument vector.
     */
    public function __construct(array $argv)
    {
        $this->scriptName = basename($argv[0] ?? 'script');
        $this->parseArguments(array_slice($argv, 1));

        $this->verbose = $this->hasOption('verbose') || $this->hasOption('v');
        $this->dryRun  = $this->hasOption('dry-run');
    }

    /**
     * Parse command-line arguments into options and positional args.
     *
     * @param array<int,string> $args  Argument list (argv without argv[0]).
     */
    private function parseArguments(array $args): void
    {
        foreach ($args as $arg) {
            if (str_starts_with($arg, '--')) {
                $parts = explode('=', substr($arg, 2), 2);
                $this->options[$parts[0]] = $parts[1] ?? true;
            } elseif (str_starts_with($arg, '-')) {
                $this->options[substr($arg, 1)] = true;
            } else {
                $this->args[] = $arg;
            }
        }
    }

    /**
     * Get positional argument by index.
     *
     * @param int   $index    Zero-based position.
     * @param mixed $default  Fallback when argument is absent.
     * @return mixed
     */
    protected function getArg(int $index, mixed $default = null): mixed
    {
        return $this->args[$index] ?? $default;
    }

    /**
     * Get option value.
     *
     * @param string $name     Option name (without leading dashes).
     * @param mixed  $default  Fallback when option is absent.
     * @return mixed
     */
    protected function getOption(string $name, mixed $default = null): mixed
    {
        return $this->options[$name] ?? $default;
    }

    /**
     * Check if option exists.
     *
     * @param string $name  Option name (without leading dashes).
     */
    protected function hasOption(string $name): bool
    {
        return isset($this->options[$name]);
    }

    // -------------------------------------------------------------------------
    // Console graphics constants
    // -------------------------------------------------------------------------

    private const ICONS = [
        'SUCCESS' => "\u{2713}", // ✓
        'ERROR'   => "\u{2717}", // ✗
        'WARNING' => "\u{26A0}", // ⚠
        'INFO'    => "\u{2192}", // →
    ];

    private const ANSI = [
        'ERROR'   => "\033[31m",
        'SUCCESS' => "\033[32m",
        'WARNING' => "\033[33m",
        'INFO'    => "\033[36m",
        'BOLD'    => "\033[1m",
        'DIM'     => "\033[2m",
        'GRAY'    => "\033[90m",
        'CYAN'    => "\033[36m",
        'MAGENTA' => "\033[35m",
        'RESET'   => "\033[0m",
    ];

    /** Cached terminal-colour detection result. */
    private ?bool $cliColorEnabled = null;

    // -------------------------------------------------------------------------
    // Colour helper
    // -------------------------------------------------------------------------

    /**
     * Return whether ANSI colour output should be used.
     */
    protected function isColorEnabled(): bool
    {
        if ($this->cliColorEnabled !== null) {
            return $this->cliColorEnabled;
        }
        if (isset($this->options['no-color']) || getenv('NO_COLOR') !== false) {
            return $this->cliColorEnabled = false;
        }
        return $this->cliColorEnabled = stream_isatty(STDOUT);
    }

    /**
     * Wrap text in an ANSI colour; returns plain text when colour is off.
     */
    protected function colorize(string $code, string $text): string
    {
        if (!$this->isColorEnabled()) {
            return $text;
        }
        return $code . $text . self::ANSI['RESET'];
    }

    /**
     * Return the terminal width (defaults to 80).
     */
    protected function termWidth(): int
    {
        $cols = (int) getenv('COLUMNS');
        return ($cols > 40) ? $cols : 80;
    }

    // -------------------------------------------------------------------------
    // Logging
    // -------------------------------------------------------------------------

    /**
     * Print a levelled message to stdout.
     *
     * @param string $message  Text to display.
     * @param string $level    One of INFO, SUCCESS, WARNING, ERROR.
     */
    protected function log(string $message, string $level = 'INFO'): void
    {
        $level = strtoupper($level);
        $color = self::ANSI[$level] ?? '';
        $icon  = self::ICONS[$level] ?? self::ICONS['INFO'];
        $reset = self::ANSI['RESET'];

        if ($this->isColorEnabled()) {
            $badge = "{$color}" . self::ANSI['BOLD'] . "[{$level}]{$reset}";
            $icon  = "{$color}{$icon}{$reset}";
        } else {
            $badge = "[{$level}]";
        }

        $line = "{$icon} {$badge} {$message}\n";

        if ($level === 'ERROR') {
            fwrite(STDERR, $line);
        } else {
            echo $line;
        }
    }

    /**
     * Print verbose message (only when --verbose or -v is set).
     *
     * @param string $message  Text to display.
     */
    protected function verbose(string $message): void
    {
        if ($this->verbose) {
            $this->log($message, 'INFO');
        }
    }

    /**
     * Print error message and exit.
     *
     * @param string $message   Error text.
     * @param int    $exitCode  Process exit code.
     * @return never
     */
    protected function error(string $message, int $exitCode = 1): never
    {
        $this->log($message, 'ERROR');
        exit($exitCode);
    }

    /**
     * Print success message.
     *
     * @param string $message  Text to display.
     */
    protected function success(string $message): void
    {
        $this->log($message, 'SUCCESS');
    }

    /**
     * Print warning message.
     *
     * @param string $message  Text to display.
     */
    protected function warning(string $message): void
    {
        $this->log($message, 'WARNING');
    }

    /**
     * Ask user for confirmation (reads from stdin).
     *
     * @param string $question  Prompt text.
     * @return bool  True when user enters 'y'.
     */
    protected function confirm(string $question): bool
    {
        echo "{$question} [y/N]: ";
        $handle = fopen('php://stdin', 'r');
        $line   = fgets($handle);
        fclose($handle);
        return strtolower(trim((string) $line)) === 'y';
    }

    /**
     * Print usage/help information.
     */
    abstract protected function showHelp(): void;

    /**
     * Main execution method.
     *
     * @return int  Exit code (0 = success).
     */
    abstract protected function execute(): int;

    /**
     * Run the application, dispatching --help and catching exceptions.
     *
     * @return int  Exit code.
     */
    public function run(): int
    {
        if ($this->hasOption('help') || $this->hasOption('h')) {
            $this->showHelp();
            return 0;
        }

        if ($this->dryRun) {
            $this->warning('Dry-run mode enabled - no changes will be made');
        }

        try {
            return $this->execute();
        } catch (\Exception $e) {
            $this->log('Error: ' . $e->getMessage(), 'ERROR');
            return 1;
        }
    }

    /**
     * Execute a shell command and return its output.
     *
     * In dry-run mode the command is logged but not executed.
     *
     * @param string      $command   Shell command string.
     * @param array|null  &$output   Lines of output (populated by reference).
     * @param int|null    &$exitCode Process exit code (populated by reference).
     * @return string  Last line of output.
     */
    protected function exec(string $command, ?array &$output = null, ?int &$exitCode = null): string
    {
        $this->verbose("Executing: {$command}");

        if ($this->dryRun) {
            $this->log("[DRY-RUN] Would execute: {$command}");
            return '';
        }

        $result = exec($command, $output, $exitCode);

        if ($exitCode !== 0) {
            $this->warning("Command failed with exit code {$exitCode}");
        }

        return (string) $result;
    }

    /**
     * Run command and return success status.
     *
     * @param string $command  Shell command string.
     * @return bool  True when exit code is 0.
     */
    protected function runCommand(string $command): bool
    {
        $exitCode = 0;
        $this->exec($command, $output, $exitCode);
        return $exitCode === 0;
    }

    /**
     * Read file contents.
     *
     * @param string $path  File path to read.
     * @return string  File contents.
     * @throws \RuntimeException  When file does not exist.
     */
    protected function readFile(string $path): string
    {
        if (!file_exists($path)) {
            throw new \RuntimeException("File not found: {$path}");
        }
        return (string) file_get_contents($path);
    }

    /**
     * Write file contents, creating parent directories as needed.
     *
     * In dry-run mode the write is logged but not performed.
     *
     * @param string $path     Destination file path.
     * @param string $content  Content to write.
     */
    protected function writeFile(string $path, string $content): void
    {
        if ($this->dryRun) {
            $this->log("[DRY-RUN] Would write to: {$path}");
            return;
        }

        $dir = dirname($path);
        if (!is_dir($dir)) {
            mkdir($dir, 0755, true);
        }

        file_put_contents($path, $content);
        $this->verbose("Written: {$path}");
    }

    /**
     * Copy a file, creating the destination directory if needed.
     *
     * In dry-run mode the copy is logged but not performed.
     *
     * @param string $source  Source file path.
     * @param string $dest    Destination file path.
     */
    protected function copyFile(string $source, string $dest): void
    {
        if ($this->dryRun) {
            $this->log("[DRY-RUN] Would copy: {$source} -> {$dest}");
            return;
        }

        $dir = dirname($dest);
        if (!is_dir($dir)) {
            mkdir($dir, 0755, true);
        }

        copy($source, $dest);
        $this->verbose("Copied: {$source} -> {$dest}");
    }

    /**
     * Delete a file or directory.
     *
     * In dry-run mode the deletion is logged but not performed.
     *
     * @param string $path  Path to delete.
     */
    protected function delete(string $path): void
    {
        if ($this->dryRun) {
            $this->log("[DRY-RUN] Would delete: {$path}");
            return;
        }

        if (is_dir($path)) {
            $this->deleteDirectory($path);
        } elseif (file_exists($path)) {
            unlink($path);
        }

        $this->verbose("Deleted: {$path}");
    }

    // -------------------------------------------------------------------------
    // Console graphics — visual primitives
    // -------------------------------------------------------------------------

    /**
     * Print a script header banner with name and description.
     *
     * @param string $name  Script name.
     * @param string $desc  One-line description.
     * @param string $ver   Version string.
     */
    protected function printBanner(string $name, string $desc = '', string $ver = '04.00.15'): void
    {
        $w     = min($this->termWidth(), 70);
        $inner = $w - 2;
        $h     = "\u{2500}";
        $v     = "\u{2502}";
        $tl    = "\u{250C}";
        $tr    = "\u{2510}";
        $bl    = "\u{2514}";
        $br    = "\u{2518}";

        $title   = " {$name}  v{$ver}";
        $titlePad = str_pad($title, $inner);
        $descPad  = ($desc !== '') ? str_pad(" {$desc}", $inner) : null;

        echo "\n";
        echo $this->colorize(self::ANSI['CYAN'], $tl . str_repeat($h, $inner) . $tr) . "\n";
        echo $this->colorize(self::ANSI['CYAN'], $v)
            . $this->colorize(self::ANSI['BOLD'], $titlePad)
            . $this->colorize(self::ANSI['CYAN'], $v) . "\n";
        if ($descPad !== null) {
            echo $this->colorize(self::ANSI['CYAN'], $v)
                . $this->colorize(self::ANSI['DIM'], $descPad)
                . $this->colorize(self::ANSI['CYAN'], $v) . "\n";
        }
        echo $this->colorize(self::ANSI['CYAN'], $bl . str_repeat($h, $inner) . $br) . "\n\n";
    }

    /**
     * Print a section header rule.
     *
     * Output example:   ── Section Title ──────────────────────────
     */
    protected function section(string $title): void
    {
        $h    = "\u{2500}";
        $w    = $this->termWidth();
        $text = " {$title} ";
        $fill = max(0, $w - strlen($text) - 4);
        echo "\n";
        echo $this->colorize(
            self::ANSI['CYAN'],
            str_repeat($h, 2) . $text . str_repeat($h, $fill)
        ) . "\n\n";
    }

    /**
     * Print a plain horizontal divider.
     */
    protected function printDivider(): void
    {
        echo $this->colorize(
            self::ANSI['DIM'],
            str_repeat("\u{2500}", $this->termWidth())
        ) . "\n";
    }

    /**
     * Print a single pass/fail status line.
     *
     * @param bool   $passed  Whether the check passed.
     * @param string $label   Check description.
     * @param string $detail  Optional detail in dim text.
     */
    protected function statusLine(bool $passed, string $label, string $detail = ''): void
    {
        [$icon, $color] = $passed
            ? ["\u{2713}", self::ANSI['SUCCESS']]
            : ["\u{2717}", self::ANSI['ERROR']];

        $suffix = ($detail !== '')
            ? '  ' . $this->colorize(self::ANSI['DIM'], "— {$detail}")
            : '';

        echo '  ' . $this->colorize($color . self::ANSI['BOLD'], $icon)
            . '  ' . $label . $suffix . "\n";
    }

    /**
     * Render an in-place progress bar.
     *
     * @param int    $current  Items done.
     * @param int    $total    Total items.
     * @param string $label    Optional trailing label.
     * @param bool   $newline  Finish bar with newline.
     */
    protected function progress(int $current, int $total, string $label = '', bool $newline = false): void
    {
        $barWidth = min(30, $this->termWidth() - 22);
        $filled   = ($total > 0) ? (int) round($barWidth * $current / $total) : 0;
        $pct      = ($total > 0) ? (int) round(100 * $current / $total) : 0;

        $bar = $this->colorize(self::ANSI['SUCCESS'], str_repeat("\u{2588}", $filled))
             . $this->colorize(self::ANSI['DIM'], str_repeat("\u{2591}", $barWidth - $filled));

        $line = sprintf(
            '  [%s] %s  %s%s',
            $bar,
            $this->colorize(self::ANSI['BOLD'], sprintf('%3d%%', $pct)),
            $this->colorize(self::ANSI['DIM'], "({$current}/{$total})"),
            ($label !== '') ? "  {$label}" : ''
        );

        echo $newline ? "\r{$line}\n" : "\r{$line}";
    }

    /**
     * Print a bordered summary box.
     *
     * @param array<string, string|int|float> $rows   Label => value pairs.
     * @param bool|null                       $passed Border colour: green/red/cyan.
     */
    protected function printSummaryBox(array $rows, ?bool $passed = null): void
    {
        $color = match ($passed) {
            true    => self::ANSI['SUCCESS'],
            false   => self::ANSI['ERROR'],
            default => self::ANSI['CYAN'],
        };

        $h     = "\u{2500}";
        $v     = "\u{2502}";
        $tl    = "\u{250C}";
        $tr    = "\u{2510}";
        $bl    = "\u{2514}";
        $br    = "\u{2518}";

        $maxKey = max(array_map('strlen', array_keys($rows)));
        $inner  = $maxKey + 20;

        echo "\n";
        echo $this->colorize($color, $tl . str_repeat($h, $inner) . $tr) . "\n";
        foreach ($rows as $label => $value) {
            $valStr  = (string) $value;
            $padding = $inner - strlen($label) - strlen($valStr) - 4;
            $row     = '  ' . $this->colorize(self::ANSI['BOLD'], $label)
                . str_repeat(' ', max(1, $padding)) . $valStr . '  ';
            echo $this->colorize($color, $v) . $row . $this->colorize($color, $v) . "\n";
        }
        echo $this->colorize($color, $bl . str_repeat($h, $inner) . $br) . "\n\n";
    }

    // -------------------------------------------------------------------------
    // Recursively delete a directory (private — used by delete())
    // -------------------------------------------------------------------------

    /**
     * Recursively delete a directory and all its contents.
     *
     * @param string $dir  Directory path.
     */
    private function deleteDirectory(string $dir): void
    {
        if (!is_dir($dir)) {
            return;
        }

        $files = array_diff((array) scandir($dir), ['.', '..']);
        foreach ($files as $file) {
            $path = "{$dir}/{$file}";
            is_dir($path) ? $this->deleteDirectory($path) : unlink($path);
        }

        rmdir($dir);
    }
}