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/Cast.php

@@ -1,32 +1,34 @@
 <?php
 
+declare(strict_types=1);
+
 require_once __DIR__ . '/BaseModel.php';
 require_once __DIR__ . '/../services/ImageHandler.php';
 
 class Cast extends BaseModel {
-    protected $table = 'cast_staff';
-    private $imageHandler;
-    protected $isUpdate = false;
-    protected $castId = null;
-    
-    public function __construct($pdo) {
+    protected string $table = 'cast_staff';
+    private ImageHandler $imageHandler;
+    protected bool $isUpdate = false;
+    protected ?int $castId = null;
+
+    public function __construct(PDO $pdo) {
         parent::__construct($pdo);
         $this->imageHandler = new ImageHandler();
     }
-    
-    public function getWithFilmography($id) {
+
+    public function getWithFilmography(?int $id): ?array {
         $cast = $this->findById($id);
         if (!$cast) {
             return null;
         }
-        
+
         $cast['occupations'] = $this->getRelatedItems('occupations', $id, 'cast_id');
         $cast['filmography'] = $this->getMediaForCast($id);
-        
+
         return $cast;
     }
-    
-    public function getMediaForCast($castId) {
+
+    public function getMediaForCast(?int $castId): array {
         $stmt = $this->pdo->prepare("
             SELECT m.id, m.title, m.year, m.poster, m.category, m.type, mc.role, mc.characterName
             FROM media m
@@ -37,8 +39,8 @@ class Cast extends BaseModel {
         $stmt->execute([$castId]);
         return $stmt->fetchAll();
     }
-    
-    public function search($filters = [], $page = 1, $limit = 20) {
+
+    public function search(array $filters = [], int $page = 1, int $limit = 20): array {
         $conditions = [];
         
         if (isset($filters['search'])) {
@@ -88,7 +90,7 @@ class Cast extends BaseModel {
         ];
     }
     
-    protected function processPhotoField($data) {
+    protected function processPhotoField(array $data): array {
         error_log("Cast::processPhotoField - Checking for photo field, isUpdate: " . ($this->isUpdate ? 'yes' : 'no'));
         
         if ($this->isUpdate && $this->castId && isset($data['photo']) && !empty($data['photo'])) {
@@ -124,7 +126,7 @@ class Cast extends BaseModel {
         return $data;
     }
     
-    public function createWithOccupations($data) {
+    public function createWithOccupations(array $data): int {
         $name = $data['name'] ?? null;
         if (!$name) {
             throw new Exception('Name is required');
@@ -153,7 +155,7 @@ class Cast extends BaseModel {
         return $castId;
     }
     
-    public function updateWithOccupations($id, $data) {
+    public function updateWithOccupations(int $id, array $data): bool {
         $this->isUpdate = true;
         $this->castId = $id;
         
@@ -184,13 +186,13 @@ class Cast 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 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();
@@ -201,7 +203,7 @@ class Cast extends BaseModel {
         return $result;
     }
     
-    protected function saveRelatedItems($table, $id, $items, $fkColumn = 'media_id') {
+    protected function saveRelatedItems(string $table, int $id, array $items, string $fkColumn = 'media_id'): void {
         $valueColumn = $fkColumn === 'cast_id' ? 'occupation' : 'genre';
         $stmt = $this->pdo->prepare("INSERT INTO $table ($fkColumn, $valueColumn) VALUES (?, ?)");
         foreach ($items as $item) {