Toolvana: production-ready media tools platform (CodeIgniter 4)

- 134-tool registry with programmatic SEO (unique titles/H1/descriptions,
  JSON-LD graphs, sitemap index, canonical 301 enforcement via required filter)
- DB-backed job queue (SKIP LOCKED) with drivers: Ffmpeg, Images (GD),
  Pdf (qpdf/gs/poppler), Youtube (thumbnails), Qr (server-side PNG)
- Security: SSRF guard, MIME validation, rate limits, API-key auth,
  bcrypt admin login, security headers
- Admin panel: dashboard, tools/categories/guides CRUD, SEO audit,
  analytics, job inspector with retry, system health, feature flags
- Docker deployment (nginx + web/api FPM pools + scalable workers),
  PHPUnit suite (19 tests / 1139 assertions), PWA manifest + service worker

app/Commands/MediaCleanup.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Commands;
+
+use App\Libraries\Pipeline;
+use App\Models\JobModel;
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+
+/**
+ * Retention reaper — deletes expired input/output files and their rows.
+ * Schedule every few minutes (cron / scheduler container):
+ *
+ *   php spark media:cleanup
+ */
+final class MediaCleanup extends BaseCommand
+{
+    protected $group       = 'Toolvana';
+    protected $name        = 'media:cleanup';
+    protected $description = 'Delete expired uploads, outputs and job rows per retention policy.';
+    protected $usage       = 'media:cleanup';
+
+    public function run(array $params): void
+    {
+        $jobs     = model(JobModel::class);
+        $deleted  = 0;
+        $freed    = 0;
+
+        foreach ([...$jobs->findExpired(), ...$jobs->findOldFailed()] as $job) {
+            foreach (['input_file' => Pipeline::incomingDir(), 'output_file' => Pipeline::storageDir()] as $field => $dir) {
+                if (! empty($job[$field])) {
+                    $path = rtrim((string) $dir, '/') . '/' . basename((string) $job[$field]);
+                    if (is_file($path)) {
+                        $freed += (int) @filesize($path);
+                        @unlink($path);
+                    }
+                }
+            }
+            $jobs->delete($job['id']);
+            ++$deleted;
+        }
+
+        // orphaned files with no row (worker crash leftovers)
+        $cutoff = time() - max(2, config('Site')->retentionHours) * 3600 - 600;
+        foreach ([Pipeline::incomingDir(), Pipeline::storageDir()] as $dir) {
+            foreach (glob(rtrim($dir, '/') . '/*') ?: [] as $file) {
+                if (is_file($file) && filemtime($file) < $cutoff) {
+                    $freed += (int) @filesize($file);
+                    @unlink($file);
+                }
+            }
+        }
+
+        CLI::write("Cleanup: {$deleted} job row(s) removed, " . number_format($freed / 1048576, 1) . ' MB freed.', 'yellow');
+    }
+}

app/Commands/QueueWork.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Commands;
+
+use App\Libraries\Pipeline;
+use App\Models\JobModel;
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+
+/**
+ * Queue worker. Run several instances for horizontal scaling:
+ *
+ *   php spark queue:work            # single pass over the queue
+ *   php spark queue:work --loop     # long-running worker (supervisor/docker)
+ *   php spark queue:work --max-jobs=50
+ */
+final class QueueWork extends BaseCommand
+{
+    protected $group       = 'Toolvana';
+    protected $name        = 'queue:work';
+    protected $description = 'Process queued media jobs (FFmpeg, images, PDFs).';
+    protected $usage       = 'queue:work [options]';
+    protected $options     = [
+        '--loop'     => 'Keep running until stopped',
+        '--sleep'    => 'Seconds between polls when idle (default 2)',
+        '--max-jobs' => 'Exit after N successful jobs',
+        '--stale'    => 'Also reap jobs stuck in processing beyond max runtime',
+    ];
+
+    public function run(array $params): void
+    {
+        $loop    = array_key_exists('loop', $params) || CLI::getOption('loop');
+        $sleep   = (int) ($params['sleep'] ?? 2);
+        $maxJobs = isset($params['max-jobs']) ? (int) $params['max-jobs'] : 0;
+        $jobs    = model(JobModel::class);
+        $done    = 0;
+
+        do {
+            $job = null;
+
+            // claim with retry: SKIP LOCKED can race under contention
+            try {
+                $job = $jobs->claimNext();
+            } catch (\Throwable $e) {
+                log_message('error', 'worker claim failed: {m}', ['m' => $e->getMessage()]);
+                usleep(500_000);
+            }
+
+            if ($job === null) {
+                if (! $loop) {
+                    break;
+                }
+                sleep(max(1, $sleep));
+                continue;
+            }
+
+            CLI::write("Processing job {$job['id']} [{$job['operation']}]", 'green');
+            self::heartbeat();
+            service('pipeline')->process($job);
+            ++$done;
+
+            if ($done % 10 === 0) {
+                self::reapStale($jobs); // periodic housekeeping inside long-running workers
+            }
+
+            if ($maxJobs > 0 && $done >= $maxJobs) {
+                break;
+            }
+        } while (true);
+
+        CLI::write("Worker finished after {$done} job(s).", 'yellow');
+    }
+
+    /** Touch a cache key so the admin dashboard can see workers are alive. */
+    public static function heartbeat(): void
+    {
+        try {
+            cache()->save('tv_worker_heartbeat', gmdate('H:i:s'), 120);
+        } catch (\Throwable) {
+            // never let telemetry break processing
+        }
+    }
+
+    /** Fail jobs whose worker died mid-processing. */
+    public static function reapStale(JobModel $jobs): void
+    {
+        foreach ($jobs->findStale((int) config('Site')->maxProcessingSeconds) as $stale) {
+            Pipeline::failJob($stale['id'], 'Processing timed out.');
+        }
+    }
+}