Split detail page contracts

lib/Console/Command.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace MintyPHP\Console;
+
+/**
+ * Base class for CLI commands.
+ *
+ * Subclasses define a name (e.g. 'module:sync') and implement execute().
+ * Arguments and options are passed as a simple parsed array.
+ */
+abstract class Command
+{
+    abstract public function name(): string;
+
+    abstract public function description(): string;
+
+    /**
+     * @param list<string> $args Positional arguments (after the command name)
+     * @param array<string, string|bool> $options Parsed --key=value and --flag options
+     * @return int Exit code (0 = success)
+     */
+    abstract public function execute(array $args, array $options): int;
+}

lib/Console/Commands/DoctorCommand.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace MintyPHP\Console\Commands;
+
+use MintyPHP\Console\Command;
+
+final class DoctorCommand extends Command
+{
+    public function name(): string
+    {
+        return 'doctor';
+    }
+
+    public function description(): string
+    {
+        return 'Run system health checks';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        // doctor.php is self-contained — include and let it run
+        $scriptPath = __DIR__ . '/../../../bin/doctor.php';
+
+        // Capture the exit code by running as a subprocess to avoid
+        // the script's own exit() call terminating our process.
+        $command = PHP_BINARY . ' ' . escapeshellarg($scriptPath);
+        passthru($command, $exitCode);
+
+        return $exitCode;
+    }
+}

lib/Console/Commands/Module/AssetsSyncCommand.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class AssetsSyncCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:assets-sync';
+    }
+
+    public function description(): string
+    {
+        return 'Publish module web assets to web/modules/';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/module-cli-bootstrap.php';
+        require_once __DIR__ . '/../../../../bin/module-assets-sync.php';
+
+        return moduleAssetsSyncRun();
+    }
+}

lib/Console/Commands/Module/BuildCommand.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class BuildCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:build';
+    }
+
+    public function description(): string
+    {
+        return 'Build runtime page root with module symlinks';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/module-cli-bootstrap.php';
+        require_once __DIR__ . '/../../../../bin/module-build.php';
+
+        return moduleBuildRun();
+    }
+}

lib/Console/Commands/Module/DeactivateCommand.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class DeactivateCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:deactivate';
+    }
+
+    public function description(): string
+    {
+        return 'Run a module\'s deactivation handler (--confirm or --dry-run)';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        $moduleId = $args[0] ?? '';
+        if ($moduleId === '') {
+            fwrite(STDERR, "Usage: php bin/console module:deactivate <module-id> --confirm|--dry-run\n");
+            return 1;
+        }
+
+        // Rebuild global argv for the underlying script
+        global $argv;
+        $argv = ['module-deactivate.php', $moduleId];
+        if ($options['confirm'] ?? false) {
+            $argv[] = '--confirm';
+        }
+        if ($options['dry-run'] ?? false) {
+            $argv[] = '--dry-run';
+        }
+
+        require_once __DIR__ . '/../../../../bin/module-deactivate.php';
+
+        return moduleDeactivateRun();
+    }
+}

lib/Console/Commands/Module/MigrateCommand.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class MigrateCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:migrate';
+    }
+
+    public function description(): string
+    {
+        return 'Apply pending module SQL migrations';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/module-cli-bootstrap.php';
+        require_once __DIR__ . '/../../../../bin/module-migrate.php';
+
+        return moduleMigrateRun();
+    }
+}

lib/Console/Commands/Module/PermissionsSyncCommand.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class PermissionsSyncCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:permissions-sync';
+    }
+
+    public function description(): string
+    {
+        return 'Sync module permissions to DB and deactivate orphaned ones';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/module-cli-bootstrap.php';
+        require_once __DIR__ . '/../../../../bin/module-permissions-sync.php';
+
+        return modulePermissionsSyncRun();
+    }
+}

lib/Console/Commands/Module/RuntimeSyncCommand.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Module;
+
+use MintyPHP\Console\Command;
+
+final class RuntimeSyncCommand extends Command
+{
+    public function name(): string
+    {
+        return 'module:sync';
+    }
+
+    public function description(): string
+    {
+        return 'Run full module runtime sync (migrate, permissions, build, assets)';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/module-runtime-sync.php';
+
+        return moduleRuntimeSyncRun();
+    }
+}

lib/Console/Commands/Scheduler/RunCommand.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Scheduler;
+
+use MintyPHP\Console\Command;
+use MintyPHP\DB;
+use MintyPHP\Service\Audit\SystemAuditService;
+use MintyPHP\Service\Scheduler\SchedulerServicesFactory;
+
+final class RunCommand extends Command
+{
+    public function name(): string
+    {
+        return 'scheduler:run';
+    }
+
+    public function description(): string
+    {
+        return 'Execute due scheduled jobs';
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        require_once __DIR__ . '/../../../../bin/cli-bootstrap.php';
+
+        $exitCode = 0;
+        $startedAt = microtime(true);
+        try {
+            cliBootstrapApp('scheduler', 'bin/console scheduler:run');
+            $factory = app(SchedulerServicesFactory::class);
+            $result = $factory->createSchedulerRunService()->runDueJobs();
+            if (!($result['ok'] ?? false)) {
+                $error = (string) ($result['error'] ?? 'unexpected_error');
+                fwrite(STDERR, sprintf("scheduler run failed: %s\n", $error));
+                $exitCode = 1;
+            } else {
+                fwrite(STDOUT, sprintf(
+                    "scheduler completed: processed=%d success=%d failed=%d skipped=%d duration_ms=%d\n",
+                    (int) ($result['processed'] ?? 0),
+                    (int) ($result['success'] ?? 0),
+                    (int) ($result['failed'] ?? 0),
+                    (int) ($result['skipped'] ?? 0),
+                    (int) ($result['duration_ms'] ?? 0)
+                ));
+            }
+        } catch (\Throwable $exception) {
+            try {
+                app(SystemAuditService::class)->record('scheduler.run', 'failed', [
+                    'error_code' => 'unexpected_error',
+                    'metadata' => [
+                        'trigger_type' => 'scheduler',
+                        'run_status' => 'failed',
+                        'processed' => 0,
+                        'success_count' => 0,
+                        'failed_count' => 0,
+                        'skipped_count' => 0,
+                        'duration_ms' => max(0, (int) round((microtime(true) - $startedAt) * 1000)),
+                        'bootstrap_error' => true,
+                    ],
+                ]);
+            } catch (\Throwable) {
+                // fail-open
+            }
+
+            fwrite(STDERR, sprintf("scheduler run failed: unexpected_error: %s\n", $exception->getMessage()));
+            $exitCode = 1;
+        } finally {
+            DB::close();
+        }
+
+        return $exitCode;
+    }
+}

lib/Console/ConsoleApplication.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace MintyPHP\Console;
+
+/**
+ * Minimal CLI command dispatcher.
+ *
+ * Parses argv into command name, positional args, and --options,
+ * then dispatches to the matching registered Command instance.
+ */
+final class ConsoleApplication
+{
+    /** @var array<string, Command> */
+    private array $commands = [];
+
+    public function register(Command $command): void
+    {
+        $this->commands[$command->name()] = $command;
+    }
+
+    /**
+     * @param list<string> $argv Raw CLI arguments (including script name at [0])
+     */
+    public function run(array $argv): int
+    {
+        $commandName = $argv[1] ?? '';
+
+        if ($commandName === '' || $commandName === 'list' || $commandName === '--help') {
+            $this->printCommandList();
+            return 0;
+        }
+
+        if (!isset($this->commands[$commandName])) {
+            fwrite(STDERR, "Unknown command: {$commandName}\n\n");
+            $this->printCommandList();
+            return 1;
+        }
+
+        [$args, $options] = self::parseArgv(array_slice($argv, 2));
+
+        return $this->commands[$commandName]->execute($args, $options);
+    }
+
+    private function printCommandList(): void
+    {
+        fwrite(STDOUT, "Usage: php bin/console <command> [arguments] [options]\n\n");
+        fwrite(STDOUT, "Available commands:\n");
+
+        // Group by namespace prefix
+        $grouped = [];
+        foreach ($this->commands as $name => $command) {
+            $parts = explode(':', $name, 2);
+            $group = count($parts) === 2 ? $parts[0] : '';
+            $grouped[$group][$name] = $command->description();
+        }
+        ksort($grouped);
+
+        foreach ($grouped as $group => $commands) {
+            if ($group !== '') {
+                fwrite(STDOUT, " {$group}\n");
+            }
+            ksort($commands);
+            foreach ($commands as $name => $description) {
+                fwrite(STDOUT, sprintf("  %-30s %s\n", $name, $description));
+            }
+        }
+    }
+
+    /**
+     * @param list<string> $tokens
+     * @return array{list<string>, array<string, string|bool>}
+     */
+    private static function parseArgv(array $tokens): array
+    {
+        $args = [];
+        $options = [];
+
+        foreach ($tokens as $token) {
+            if (str_starts_with($token, '--')) {
+                $option = substr($token, 2);
+                if (str_contains($option, '=')) {
+                    [$key, $value] = explode('=', $option, 2);
+                    $options[$key] = $value;
+                } else {
+                    $options[$option] = true;
+                }
+            } else {
+                $args[] = $token;
+            }
+        }
+
+        return [$args, $options];
+    }
+}