Add strict types and type hints across API

Apply strict_types and extensive type declarations throughout the API and models, improving type safety and error handling. Key changes: add declare(strict_types=1) to many files; convert properties, method parameters and return values to typed signatures (PDO, arrays, ints, strings, bools, nullables); switch exception handling to Throwable in index and Router; improve Router, controllers and model method signatures and nullability handling; refine file/image serving security checks and headers in ImageController; strengthen Database typing and initialization methods; return explicit types from BaseModel CRUD helpers and counting; update Media/Cast/Adult/Game/Console/Settings controllers and models to use typed methods, better validation, and clearer update/create return types. Also add AGENTS.md (agent skills index), update README with Swagger/OpenAPI usage instructions, and add /.windsurf to .gitignore. These changes aim to harden runtime correctness, make intended contracts explicit, and prepare the codebase for easier maintenance and static analysis.

api/models/Media.php

@@ -1,15 +1,17 @@
 <?php
 
+declare(strict_types=1);
+
 require_once __DIR__ . '/BaseModel.php';
 
 class Media extends BaseModel {
-    protected $table = 'media';
-    
-    public function getBase($id) {
+    protected string $table = 'media';
+
+    public function getBase(?int $id): array|false {
         return $this->findById($id);
     }
 
-    public function getWithRelations($id) {
+    public function getWithRelations(?int $id): ?array {
         $media = $this->findById($id);
         if (!$media) {
             return null;
@@ -22,8 +24,8 @@ class Media extends BaseModel {
 
         return $media;
     }
-    
-    public function search($filters = [], $page = 1, $limit = 20) {
+
+    public function search(array $filters = [], int $page = 1, int $limit = 20): array {
         $conditions = [];
         
         if (isset($filters['category'])) {
@@ -99,7 +101,7 @@ class Media extends BaseModel {
         ];
     }
     
-    public function createWithRelations($data) {
+    public function createWithRelations(array $data): int {
         $title = $data['title'] ?? null;
         if (!$title) {
             throw new Exception('Title is required');
@@ -147,7 +149,7 @@ class Media extends BaseModel {
         return $mediaId;
     }
     
-    public function updateWithRelations($id, $data) {
+    public function updateWithRelations(int $id, array $data): bool {
         $mediaData = [];
         
         foreach (['title', 'year', 'poster', 'banner', 'description', 'rating', 'category', 'type', 'status', 'aspectRatio', 'runtime', 'director', 'writer', 'releaseDate', 'source'] as $field) {
@@ -186,13 +188,13 @@ class Media extends BaseModel {
         return true;
     }
     
-    public function findByCleanName($cleanname) {
+    public function findByCleanName(string $cleanname): array|false {
         $stmt = $this->pdo->prepare("SELECT * FROM {$this->table} WHERE cleanname = ?");
         $stmt->execute([$cleanname]);
         return $stmt->fetch();
     }
     
-    protected function saveRelatedItems($table, $id, $items, $fkColumn = 'media_id') {
+    protected function saveRelatedItems(string $table, int $id, array $items, string $fkColumn = 'media_id'): void {
         $valueColumn = $table === 'genres' ? 'genre' : ($table === 'tags' ? 'tag' : ($table === 'occupations' ? 'occupation' : 'studio'));
         $stmt = $this->pdo->prepare("INSERT INTO $table ($fkColumn, $valueColumn) VALUES (?, ?)");
         foreach ($items as $item) {
@@ -200,7 +202,7 @@ class Media extends BaseModel {
         }
     }
     
-    protected function getCastForMedia($mediaId) {
+    protected function getCastForMedia(?int $mediaId): array {
         $stmt = $this->pdo->prepare("
             SELECT cs.*, mc.role, mc.characterName, mc.characterImage
             FROM cast_staff cs
@@ -215,7 +217,7 @@ class Media extends BaseModel {
         return $cast;
     }
     
-    protected function getRelatedItems($table, $id, $fkColumn = 'media_id') {
+    protected function getRelatedItems(string $table, int $id, string $fkColumn = 'media_id'): array {
         $stmt = $this->pdo->prepare("SELECT * FROM $table WHERE $fkColumn = ?");
         $stmt->execute([$id]);
         $items = $stmt->fetchAll();
@@ -230,7 +232,7 @@ class Media extends BaseModel {
         return $result;
     }
     
-    protected function saveCastAssignments($mediaId, $castData) {
+    protected function saveCastAssignments(int $mediaId, array $castData): void {
         foreach ($castData as $member) {
             $castId = null;
             if (isset($member['id']) && $member['id']) {