Jonathan Miller
7b863f690d
Updated ~60 files: comments, usage docs, SCRIPT_PATH constants, wrapper paths, require paths, error messages, and help text. All api/validate/ → validate/, api/automation/ → automation/, etc. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
592 lines
15 KiB
PHP
592 lines
15 KiB
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/MokoStandards-API
|
|
* PATH: /lib/CliBase.php
|
|
* VERSION: 04.06.00
|
|
* 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);
|
|
}
|
|
}
|