Add stage 3: todo list and item CRUD API

Two migrations add todo_lists (owner_id FK to users, title, description) and
todo_items (list_id FK, text, complete, position), both with ON DELETE
CASCADE.

New endpoints under /api/lists, all behind AuthMiddleware:
  - lists: index / store / show / update (PATCH) / destroy
  - items: nested under a list, same five verbs
Lists are owner-scoped — another user's or a missing list responds 404, never
403. New items append after the highest position unless one is given; the
list carries item_count / completed_count. Item PATCH is partial and never
renumbers siblings.

Adds App\Support\Validator for request-body checks, TodoList/TodoItem
repositories, and body()/user() helpers on the Controller base. Feature tests
move their shared harness into tests/ApiTestCase; TodoTest covers CRUD,
ownership isolation, ordering, completion counts, validation and cascade
delete. Full suite: 15 passing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/Support/Validator.php

@@ -0,0 +1,141 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support;
+
+use App\Exception\ValidationException;
+
+/**
+ * Small helper for validating a decoded JSON request body. Accumulates
+ * field => messages and throws a ValidationException when asked.
+ */
+final class Validator
+{
+    /** @var array<string, string[]> */
+    private array $errors = [];
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    public function __construct(private readonly array $data)
+    {
+    }
+
+    public function has(string $field): bool
+    {
+        return array_key_exists($field, $this->data);
+    }
+
+    /**
+     * A required, non-blank, length-bounded string.
+     */
+    public function requiredString(string $field, int $max, int $min = 1): string
+    {
+        if (!$this->has($field) || $this->data[$field] === null) {
+            $this->errors[$field][] = ucfirst($field) . ' is required.';
+
+            return '';
+        }
+
+        return $this->stringValue($field, $max, $min) ?? '';
+    }
+
+    /**
+     * An optional string; returns null when the field is absent.
+     */
+    public function optionalString(string $field, int $max, int $min = 0): ?string
+    {
+        if (!$this->has($field)) {
+            return null;
+        }
+
+        return $this->stringValue($field, $max, $min);
+    }
+
+    public function optionalBool(string $field): ?bool
+    {
+        if (!$this->has($field)) {
+            return null;
+        }
+
+        $value = $this->data[$field];
+
+        if (is_bool($value)) {
+            return $value;
+        }
+        if ($value === 0 || $value === 1) {
+            return $value === 1;
+        }
+
+        $this->errors[$field][] = ucfirst($field) . ' must be true or false.';
+
+        return null;
+    }
+
+    public function optionalInt(string $field, int $min): ?int
+    {
+        if (!$this->has($field)) {
+            return null;
+        }
+
+        $value = $this->data[$field];
+
+        if (!is_int($value) || $value < $min) {
+            $this->errors[$field][] = ucfirst($field) . " must be an integer of at least {$min}.";
+
+            return null;
+        }
+
+        return $value;
+    }
+
+    public function add(string $field, string $message): void
+    {
+        $this->errors[$field][] = $message;
+    }
+
+    public function failed(): bool
+    {
+        return $this->errors !== [];
+    }
+
+    /**
+     * @throws ValidationException when any errors were recorded.
+     */
+    public function assert(): void
+    {
+        if ($this->errors !== []) {
+            throw new ValidationException($this->errors);
+        }
+    }
+
+    private function stringValue(string $field, int $max, int $min): ?string
+    {
+        $value = $this->data[$field];
+
+        if (!is_string($value)) {
+            $this->errors[$field][] = ucfirst($field) . ' must be a string.';
+
+            return null;
+        }
+
+        $value = trim($value);
+        $length = mb_strlen($value);
+
+        if ($length < $min) {
+            $this->errors[$field][] = $min === 1
+                ? ucfirst($field) . ' cannot be empty.'
+                : ucfirst($field) . " must be at least {$min} characters.";
+
+            return null;
+        }
+        if ($length > $max) {
+            $this->errors[$field][] = ucfirst($field) . " must be at most {$max} characters.";
+
+            return null;
+        }
+
+        return $value;
+    }
+}