feat: structured errors with hint, ToolResult, cursor pagination

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
2026-09-25 21:37:42 +02:00
parent 5434cb6767
commit f63d35c2f8
12 changed files with 631 additions and 14 deletions
@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use LIT\MCP\Abilities\Cursor;
+use LIT\MCP\Tests\Unit\TestCase;
+
+final class CursorTest extends TestCase
+{
+    public function testRoundTrip(): void
+    {
+        self::assertSame(40, Cursor::decode(Cursor::encode(40)));
+    }
+
+    public function testMissingCursorStartsAtZero(): void
+    {
+        self::assertSame(0, Cursor::decode(null));
+        self::assertSame(0, Cursor::decode(''));
+    }
+
+    public function testTamperedCursorIsRejected(): void
+    {
+        self::assertNull(Cursor::decode('not-a-cursor'));
+        self::assertNull(Cursor::decode(base64_encode('o:-5')));
+        self::assertNull(Cursor::decode(base64_encode('o:12;DROP')));
+    }
+
+    public function testLimitIsClamped(): void
+    {
+        self::assertSame(20, Cursor::limit(null));
+        self::assertSame(1, Cursor::limit(0));
+        self::assertSame(100, Cursor::limit(500));
+        self::assertSame(7, Cursor::limit(7));
+    }
+
+    public function testPageDetectsMoreRows(): void
+    {
+        $page = Cursor::page([1, 2, 3], 2, 10);
+
+        self::assertSame([1, 2], $page['items']);
+        self::assertSame(12, Cursor::decode($page['next_cursor']));
+        self::assertNull(Cursor::page([1, 2], 2, 0)['next_cursor']);
+    }
+
+    public function testInvalidCursorErrorIsAValidationError(): void
+    {
+        self::assertSame('lit_validation_failed', Cursor::invalid()->get_error_code());
+    }
+
+    public function testInputPropertiesDescribeLimitAndCursor(): void
+    {
+        $properties = Cursor::inputProperties();
+
+        self::assertSame(100, $properties['limit']['maximum']);
+        self::assertSame('string', $properties['cursor']['type']);
+    }
+}
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use LIT\MCP\Abilities\Errors;
+use LIT\MCP\Tests\Unit\TestCase;
+
+final class ErrorsTest extends TestCase
+{
+    public function testMessageCarriesCodeMessageHintAndFieldsAsJson(): void
+    {
+        $error = Errors::invalidInput('Titel fehlt.', ['title' => 'Pflichtfeld']);
+
+        self::assertSame('lit_validation_failed', $error->get_error_code());
+        $payload = json_decode($error->get_error_message(), true);
+        self::assertSame('validation_failed', $payload['code']);
+        self::assertSame('Titel fehlt.', $payload['message']);
+        self::assertNotSame('', $payload['hint']);
+        self::assertSame(['title' => 'Pflichtfeld'], $payload['fields']);
+        self::assertSame(400, $error->get_error_data()['status']);
+        self::assertSame($payload['hint'], $error->get_error_data()['hint']);
+    }
+
+    public function testUmlautsStayReadableInTheMessage(): void
+    {
+        $error = Errors::forbidden('Dein Benutzerkonto ist für LIT MCP nicht freigegeben.');
+
+        self::assertStringContainsString('für LIT MCP nicht freigegeben', $error->get_error_message());
+    }
+
+    public function testInUseCarriesTheUsages(): void
+    {
+        $error = Errors::inUse('Bild wird verwendet.', [['post_id' => 7, 'where' => 'featured']]);
+
+        $payload = json_decode($error->get_error_message(), true);
+        self::assertSame('lit_in_use', $error->get_error_code());
+        self::assertSame(7, $payload['usages'][0]['post_id']);
+    }
+
+    public function testEveryFactoryUsesLitPrefixAndANonEmptyHint(): void
+    {
+        $errors = [
+            Errors::forbidden('x'),
+            Errors::notFound('x'),
+            Errors::revMismatch(),
+            Errors::confirmRequired('x'),
+            Errors::unsupported('x', 'y'),
+            Errors::internal(),
+        ];
+
+        foreach ($errors as $error) {
+            self::assertStringStartsWith('lit_', $error->get_error_code());
+            self::assertNotSame('', json_decode($error->get_error_message(), true)['hint']);
+        }
+    }
+}
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use LIT\MCP\Abilities\JsonMap;
+use LIT\MCP\Abilities\Rev;
+use LIT\MCP\Tests\Unit\TestCase;
+use stdClass;
+
+final class RevAndJsonMapTest extends TestCase
+{
+    public function testRevIsShortDeterministicAndContentSensitive(): void
+    {
+        self::assertMatchesRegularExpression('/^[0-9a-f]{12}$/', Rev::of('abc'));
+        self::assertSame(Rev::of('abc'), Rev::of('abc'));
+        self::assertNotSame(Rev::of('abc'), Rev::of('abd'));
+    }
+
+    public function testEmptyMapBecomesJsonObject(): void
+    {
+        self::assertInstanceOf(stdClass::class, JsonMap::of([]));
+        self::assertSame('{}', json_encode(JsonMap::of([])));
+        self::assertSame(['a' => 1], JsonMap::of(['a' => 1]));
+    }
+}
@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use InvalidArgumentException;
+use LIT\MCP\Abilities\ToolResult;
+use LIT\MCP\Tests\Unit\TestCase;
+
+final class ToolResultTest extends TestCase
+{
+    public function testDefaultsMatchTheSpecShape(): void
+    {
+        self::assertSame(
+            [
+                'ok' => true,
+                'summary' => 'Seite angelegt',
+                'changed' => [],
+                'outline' => null,
+                'rev' => null,
+                'warnings' => [],
+                'revision_id' => null,
+                'snapshot_id' => null,
+                'log_id' => null,
+                'preview_url' => null,
+                'edit_url' => null,
+            ],
+            ToolResult::ok('Seite angelegt')->toArray()
+        );
+    }
+
+    public function testBuilderFillsAllFieldsAndExtras(): void
+    {
+        $result = ToolResult::ok('Aktualisiert')
+            ->changed('12', 'page', 'updated', 'Startseite')
+            ->warning('Bild ohne Alt-Text')
+            ->warnings(['Zweite Warnung'])
+            ->outline('Hero')
+            ->rev('a1b2c3d4e5f6')
+            ->revisionId(812)
+            ->snapshotId('snap-1')
+            ->logId(4711)
+            ->urls('https://kunde.de/?p=12&preview=true', 'https://kunde.de/wp-admin/post.php?post=12&action=edit')
+            ->with('previous', ['blogname' => 'Alt'])
+            ->toArray();
+
+        self::assertSame([['id' => '12', 'type' => 'page', 'action' => 'updated', 'label' => 'Startseite']], $result['changed']);
+        self::assertSame(['Bild ohne Alt-Text', 'Zweite Warnung'], $result['warnings']);
+        self::assertSame('Hero', $result['outline']);
+        self::assertSame('a1b2c3d4e5f6', $result['rev']);
+        self::assertSame(812, $result['revision_id']);
+        self::assertSame('snap-1', $result['snapshot_id']);
+        self::assertSame(4711, $result['log_id']);
+        self::assertSame('https://kunde.de/?p=12&preview=true', $result['preview_url']);
+        self::assertSame(['blogname' => 'Alt'], $result['previous']);
+    }
+
+    public function testReservedKeysCannotBeOverwrittenByExtras(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        ToolResult::ok('x')->with('ok', false);
+    }
+
+    public function testSchemaRequiresCoreKeysAndAcceptsExtraProperties(): void
+    {
+        $schema = ToolResult::schema(['previous' => ['type' => 'object']], ['previous']);
+
+        self::assertSame('object', $schema['type']);
+        self::assertContains('summary', $schema['required']);
+        self::assertContains('previous', $schema['required']);
+        self::assertSame(['integer', 'null'], $schema['properties']['revision_id']['type']);
+        self::assertSame(['type' => 'object'], $schema['properties']['previous']);
+    }
+}
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace LIT\MCP\Tests\Unit;

 use Brain\Monkey;
+use Brain\Monkey\Functions;
 use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
 use PHPUnit\Framework\TestCase as BaseTestCase;

@@ -16,6 +17,18 @@ abstract class TestCase extends BaseTestCase
    {
        parent::setUp();
        Monkey\setUp();
+
+        // Pure helpers with obvious behaviour. Never use Functions\expect() on these
+        // names in a test: Brain Monkey forbids a stub and an expectation for the
+        // same function. Functions\when() may still redefine them.
+        Functions\stubs([
+            'wp_json_encode' => static fn ($data, int $flags = 0) => json_encode($data, $flags),
+            'is_wp_error' => static fn ($thing): bool => $thing instanceof \WP_Error,
+            'absint' => static fn ($value): int => abs((int) $value),
+            'wp_slash' => static fn ($value) => $value,
+            'wp_unslash' => static fn ($value) => $value,
+            'sanitize_text_field' => static fn ($value): string => trim(strip_tags((string) $value)),
+        ]);
    }

    protected function tearDown(): void