feat: list and restore revisions

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
2026-09-25 23:41:39 +02:00
parent e183874ff7
commit b9dd86d223
6 changed files with 455 additions and 0 deletions
@@ -0,0 +1,156 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations\WordPress\Revisions;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\Errors;
+use LIT\MCP\Abilities\Rev;
+use LIT\MCP\Abilities\ToolResult;
+use LIT\MCP\ChangeLog\ChangeLog;
+use LIT\MCP\Integrations\WordPress\PostGuard;
+use LIT\MCP\Integrations\WordPress\RevisionPoint;
+use LIT\MCP\Integrations\WordPress\Schema\ContentSchema;
+use WP_Error;
+use WP_Post;
+
+/**
+ * lit/revision-restore: restores title, content and excerpt of an entry from one of
+ * its own revisions; the status is not touched. Because this overwrites the current
+ * content, rev of the current entry (from lit/content-get) is required (optimistic
+ * lock, spec §2 principle 7) – the restore is itself a write. Before restoring, the
+ * current state is saved as a revision (RevisionPoint::capture), so the restore is
+ * undoable via another lit/revision-restore call. A revision id that does not belong
+ * to a manageable entry (wrong post_type, or post_parent 0 – an orphaned revision) is
+ * rejected as a validation error on revision_id, the only id field this tool takes.
+ */
+final class RevisionRestoreAbility implements Ability
+{
+    public function __construct(private ContentSchema $schema, private ChangeLog $log)
+    {
+    }
+
+    public function name(): string
+    {
+        return 'lit/revision-restore';
+    }
+
+    public function label(): string
+    {
+        return 'Revision wiederherstellen';
+    }
+
+    public function description(): string
+    {
+        return 'Stellt Titel, Inhalt und Auszug eines Eintrags aus einer Revision wieder her (Status bleibt). '
+            . 'Der aktuelle Stand wird vorher als Revision gesichert (revision_id im Ergebnis). rev des Eintrags '
+            . 'aus lit-content-get ist Pflicht, damit parallele Änderungen nicht überschrieben werden. Erst nach '
+            . 'Rückfrage mit confirm: true aufrufen.';
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'revision_id' => ['type' => 'integer', 'minimum' => 1],
+                'rev' => [
+                    'type' => 'string',
+                    'description' => 'rev des Eintrags aus lit-content-get (optimistische Sperre).',
+                ],
+                'confirm' => ['type' => 'boolean', 'description' => 'true nach Bestätigung durch den Nutzer.'],
+            ],
+            'required' => ['revision_id', 'rev'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function outputSchema(): ?array
+    {
+        return ToolResult::schema();
+    }
+
+    public function annotations(): array
+    {
+        return ['readonly' => false, 'destructive' => true, 'idempotent' => true];
+    }
+
+    public function isDirect(): bool
+    {
+        return false;
+    }
+
+    public function permission(array $input): bool|WP_Error
+    {
+        $pair = $this->load($input);
+
+        return $pair instanceof WP_Error ? $pair : true;
+    }
+
+    public function execute(array $input): mixed
+    {
+        $pair = $this->load($input);
+        if ($pair instanceof WP_Error) {
+            return $pair;
+        }
+
+        [$revision, $post] = $pair;
+        $postId = (int) $post->ID;
+        if (($input['confirm'] ?? false) !== true) {
+            return Errors::confirmRequired(sprintf(
+                '"%s" (ID %d) auf den Stand vom %s zurücksetzen?',
+                $post->post_title,
+                $postId,
+                $revision->post_date
+            ));
+        }
+
+        if (! isset($input['rev']) || $input['rev'] !== Rev::ofPost($post)) {
+            return Errors::revMismatch();
+        }
+
+        $backupId = RevisionPoint::capture($postId);
+        $restored = wp_restore_post_revision((int) $revision->ID);
+        if (! $restored) {
+            return Errors::unsupported(
+                'WordPress konnte die Revision nicht wiederherstellen.',
+                'Revision in WordPress unter „Revisionen“ prüfen.'
+            );
+        }
+
+        do_action('lit_mcp_after_save', $postId, $this->name(), $input);
+        $updated = get_post($postId);
+        $updated = $updated instanceof WP_Post ? $updated : $post;
+        $summary = sprintf('"%s" auf Stand vom %s zurückgesetzt', $updated->post_title, $revision->post_date);
+        $postType = (string) $post->post_type;
+        $logId = $this->log->record($this->name(), $postType, (string) $postId, $summary, $backupId);
+
+        return ToolResult::ok($summary . sprintf(' (Status unverändert: %s).', $updated->post_status))
+            ->changed((string) $postId, $postType, 'restored', (string) $updated->post_title)
+            ->rev(Rev::ofPost($updated))
+            ->revisionId($backupId)
+            ->logId($logId)
+            ->urls((string) get_preview_post_link($updated), (string) get_edit_post_link($postId, 'raw'))
+            ->toArray();
+    }
+
+    /**
+     * @param array<string, mixed> $input
+     * @return array{0: WP_Post, 1: WP_Post}|WP_Error
+     */
+    private function load(array $input): array|WP_Error
+    {
+        $revisionId = PostGuard::id($input['revision_id'] ?? null);
+        $revision = $revisionId === null ? null : get_post($revisionId);
+        if (! $revision instanceof WP_Post || $revision->post_type !== 'revision') {
+            return Errors::notFound('Revision nicht gefunden.', 'Revisionen über lit-revisions-list abrufen.');
+        }
+
+        // field 'revision_id': post_parent 0 (an orphaned revision) is the only id this
+        // input carries, so a validation error must name revision_id, not post_id.
+        $post = PostGuard::editable((int) $revision->post_parent, $this->schema, 'revision_id');
+
+        return $post instanceof WP_Error ? $post : [$revision, $post];
+    }
+}
@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations\WordPress\Revisions;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\Cursor;
+use LIT\MCP\Integrations\WordPress\PostGuard;
+use LIT\MCP\Integrations\WordPress\Schema\ContentSchema;
+use WP_Error;
+use WP_Post;
+
+/**
+ * lit/revisions-list: revisions of an entry, newest first. Autosaves are included
+ * (marked autosave: true) rather than filtered out, so the client can decide.
+ */
+final class RevisionsListAbility implements Ability
+{
+    public function __construct(private ContentSchema $schema)
+    {
+    }
+
+    public function name(): string
+    {
+        return 'lit/revisions-list';
+    }
+
+    public function label(): string
+    {
+        return 'Revisionen auflisten';
+    }
+
+    public function description(): string
+    {
+        return 'Listet die gespeicherten Revisionen eines Eintrags (neueste zuerst) mit Datum, Autor und '
+            . 'Textauszug. Wiederherstellen mit lit-revision-restore.';
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => array_merge(
+                ['post_id' => ['type' => 'integer', 'minimum' => 1]],
+                Cursor::inputProperties()
+            ),
+            'required' => ['post_id'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function outputSchema(): ?array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'post_id' => ['type' => 'integer'],
+                'items' => [
+                    'type' => 'array',
+                    'items' => [
+                        'type' => 'object',
+                        'properties' => [
+                            'id' => ['type' => 'integer'],
+                            'date' => ['type' => 'string'],
+                            'author' => ['type' => 'object'],
+                            'title' => ['type' => 'string'],
+                            'autosave' => ['type' => 'boolean'],
+                            'excerpt' => ['type' => 'string'],
+                        ],
+                        'required' => ['id', 'date', 'author', 'title', 'autosave', 'excerpt'],
+                    ],
+                ],
+                'next_cursor' => ['type' => ['string', 'null']],
+            ],
+            'required' => ['post_id', 'items', 'next_cursor'],
+        ];
+    }
+
+    public function annotations(): array
+    {
+        return ['readonly' => true, 'destructive' => false, 'idempotent' => true];
+    }
+
+    public function isDirect(): bool
+    {
+        return false;
+    }
+
+    public function permission(array $input): bool|WP_Error
+    {
+        $post = PostGuard::editable($input['post_id'] ?? null, $this->schema);
+
+        return $post instanceof WP_Error ? $post : true;
+    }
+
+    public function execute(array $input): mixed
+    {
+        $post = PostGuard::editable($input['post_id'] ?? null, $this->schema);
+        if ($post instanceof WP_Error) {
+            return $post;
+        }
+
+        $offset = Cursor::decode(isset($input['cursor']) ? (string) $input['cursor'] : null);
+        if ($offset === null) {
+            return Cursor::invalid();
+        }
+
+        $limit = Cursor::limit($input['limit'] ?? null);
+        $revisions = wp_get_post_revisions((int) $post->ID, ['posts_per_page' => $limit + 1, 'offset' => $offset]);
+        $page = Cursor::page(array_values(is_array($revisions) ? $revisions : []), $limit, $offset);
+
+        return [
+            'post_id' => (int) $post->ID,
+            'items' => array_map(fn (WP_Post $revision): array => $this->item($revision), $page['items']),
+            'next_cursor' => $page['next_cursor'],
+        ];
+    }
+
+    /** @return array<string, mixed> */
+    private function item(WP_Post $revision): array
+    {
+        $text = trim((string) preg_replace('/\s+/u', ' ', wp_strip_all_tags((string) $revision->post_content)));
+
+        return [
+            'id' => (int) $revision->ID,
+            'date' => (string) $revision->post_date,
+            'author' => [
+                'id' => (int) $revision->post_author,
+                'name' => (string) get_the_author_meta('display_name', (int) $revision->post_author),
+            ],
+            'title' => (string) $revision->post_title,
+            'autosave' => (bool) wp_is_post_autosave($revision),
+            'excerpt' => mb_substr($text, 0, 160),
+        ];
+    }
+}