feat: lit/divi-insert and lit/divi-update

All-or-nothing at ability level (S39), duplicate ids refused (S14),
set and attrs on the same path refused (S38), invalid_attr_path error.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7

src/Abilities/Errors.php

@@ -101,6 +101,24 @@ final class Errors
         return self::make('unsupported', $message, $hint, 400);
     }
 
+    /**
+     * Unknown Divi attribute paths (spec §5.4, §8.2). $fields names every problem of the call,
+     * the unknown paths with their closest known ones.
+     *
+     * @param array<string, string> $fields Input path => problem.
+     */
+    public static function invalidAttrPath(array $fields): WP_Error
+    {
+        return self::make(
+            'invalid_attr_path',
+            'Unbekannte Attributpfade; nichts wurde gespeichert.',
+            'Vorschläge unter fields prüfen; alle gültigen Pfade eines Moduls liefert lit/divi-catalog '
+                . '(direkt: lit-divi-catalog) mit module.',
+            400,
+            ['fields' => $fields]
+        );
+    }
+
     /**
      * A write failed and was rolled back completely.
      *

src/Integrations/Divi/Compose/Composer.php

@@ -116,6 +116,7 @@ final class Composer
             }
         }
 
+        $this->overlaps($block->shortName(), $change, $field);
         $attrs = $this->presetAndAttrs($block->name(), $attrs, $change, $field);
         if (array_key_exists('label', $change)) {
             $attrs = $change['label'] === null || $change['label'] === ''
@@ -126,6 +127,39 @@ final class Composer
         return ['attrs' => $attrs, 'errors' => $this->errors, 'invalid_paths' => $this->invalidPaths];
     }
 
+    /**
+     * Ruling S38: one change may not reach the same attribute path through "set" and "attrs" –
+     * composite values are replaced whole per breakpoint, so combining them would silently lose
+     * sub-keys. Paths overlap when equal or when one lies below the other.
+     *
+     * @param array<array-key, mixed> $change
+     */
+    private function overlaps(string $type, array $change, string $field): void
+    {
+        $set = $change['set'] ?? null;
+        $full = $change['attrs'] ?? null;
+        if (! is_array($set) || ! is_array($full) || $set === [] || $full === []) {
+            return;
+        }
+
+        $short = $this->shortform->paths($type, array_map('strval', array_keys($set)));
+        foreach (array_keys($full) as $path) {
+            $path = (string) $path;
+            foreach ($short as $name => $shortPath) {
+                if (
+                    $path === $shortPath || str_starts_with($path, $shortPath . '.')
+                    || str_starts_with($shortPath, $path . '.')
+                ) {
+                    $this->errors[$field . '.attrs.' . $path] = sprintf(
+                        'derselbe Attributpfad wird auch über set.%s geändert; bitte als zwei Änderungen senden',
+                        $name
+                    );
+                    break;
+                }
+            }
+        }
+    }
+
     /** Admin label for a new module: "<Abschnitt> – <Modultitel>" or the title alone. */
     public function autoLabel(string $name, string $context): string
     {

src/Integrations/Divi/Compose/ShortformWriter.php

@@ -72,6 +72,25 @@ final class ShortformWriter
         return ['attrs' => $attrs, 'errors' => $errors];
     }
 
+    /**
+     * Attribute paths the given short-form fields of $type write to (unknown fields left out).
+     *
+     * @param list<string> $names Field names.
+     * @return array<string, string> Field => attribute path.
+     */
+    public function paths(string $type, array $names): array
+    {
+        $fields = $this->modules === null ? ShortformMap::fields($type) : ($this->modules[$type] ?? []);
+        $paths = [];
+        foreach ($names as $name) {
+            if (isset($fields[$name]['path'])) {
+                $paths[$name] = (string) $fields[$name]['path'];
+            }
+        }
+
+        return $paths;
+    }
+
     /**
      * The short-form color check (ruling S13; Task 3 reuses it for background_color): a
      * placeholder or reference that is a color reference, or a plain CSS color – checked

src/Integrations/Divi/DiviIntegration.php

@@ -4,11 +4,17 @@ declare(strict_types=1);
 
 namespace LIT\MCP\Integrations\Divi;
 
+use LIT\MCP\ChangeLog\ChangeLog;
 use LIT\MCP\Integrations\Divi\Design\DesignSystemReader;
 use LIT\MCP\Integrations\Divi\Design\DiviDesignSystemAbility;
+use LIT\MCP\Integrations\Divi\Pages\DiviComposition;
+use LIT\MCP\Integrations\Divi\Pages\DiviInsertAbility;
 use LIT\MCP\Integrations\Divi\Pages\DiviNodeGetAbility;
 use LIT\MCP\Integrations\Divi\Pages\DiviOutlineAbility;
 use LIT\MCP\Integrations\Divi\Pages\DiviPageLoader;
+use LIT\MCP\Integrations\Divi\Pages\DiviSaver;
+use LIT\MCP\Integrations\Divi\Pages\DiviUpdateAbility;
+use LIT\MCP\Integrations\Divi\Pages\DiviWriter;
 use LIT\MCP\Integrations\Divi\Schema\DiviCatalogAbility;
 use LIT\MCP\Integrations\Divi\Schema\DiviModules;
 use LIT\MCP\Integrations\Integration;
@@ -16,14 +22,15 @@ use LIT\MCP\Integrations\WordPress\Schema\ContentSchema;
 
 /**
  * Divi 5 pages (spec §5, Etappe 2). Only available when the Divi 5 builder is loaded
- * (spec §2 principle 4); Divi 4 is never edited (spec §3.4).
+ * (spec §2 principle 4); Divi 4 is never edited (spec §3.4). The write abilities share one
+ * DiviWriter; each binds the composition to its entry via DiviWriter::composition().
  */
 final class DiviIntegration implements Integration
 {
     private DiviModules $modules;
     private DesignSystemReader $design;
 
-    public function __construct(private ContentSchema $schema)
+    public function __construct(private ContentSchema $schema, private ChangeLog $log)
     {
         $this->modules = new DiviModules();
         $this->design = new DesignSystemReader();
@@ -42,12 +49,16 @@ final class DiviIntegration implements Integration
     public function abilities(): array
     {
         $loader = new DiviPageLoader($this->schema);
+        $composition = new DiviComposition($this->modules, $this->design);
+        $writer = new DiviWriter($loader, new DiviSaver(), $this->log, $this->design, $composition);
 
         return [
             new DiviOutlineAbility($loader, $this->design),
             new DiviNodeGetAbility($loader, $this->design),
             new DiviCatalogAbility($this->modules),
             new DiviDesignSystemAbility($this->design),
+            new DiviInsertAbility($writer),
+            new DiviUpdateAbility($writer),
         ];
     }
 }

src/Integrations/Divi/Pages/DiviInsertAbility.php

@@ -0,0 +1,130 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations\Divi\Pages;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\Errors;
+use LIT\MCP\Abilities\ToolResult;
+use WP_Error;
+
+/**
+ * lit/divi-insert: inserts nodes in short and/or full form – modules, rows or whole sections –
+ * at parent / before / after (spec §5.7). All or nothing (ruling S39): the whole input is
+ * validated first and every error is returned together; the blocks come only from Composer
+ * (client values pass its choke point) and enter the tree only through TreeEditor::insert(),
+ * which also wraps the first section of an empty page in divi/placeholder (ruling S9).
+ */
+final class DiviInsertAbility implements Ability
+{
+    public function __construct(private DiviWriter $writer)
+    {
+    }
+
+    public function name(): string
+    {
+        return 'lit/divi-insert';
+    }
+
+    public function label(): string
+    {
+        return 'Divi-Knoten einfügen';
+    }
+
+    public function description(): string
+    {
+        return 'Fügt Divi-Knoten ein: Module, Zeilen oder ganze Abschnitte in Kurzform (z. B. {"type": "button", '
+            . '"text": "Termin buchen", "url": "/kontakt", "preset": "CTA primär"}) und/oder Vollform ("attrs"). '
+            . 'Position über parent, before oder after (Pfad-IDs aus lit-divi-outline), sonst ans Seitenende. '
+            . 'Platzhalter wie {{color:primary}} statt fester Werte. tree_rev ist Pflicht; alles oder nichts. '
+            . 'Format: lit-guide topic "divi-shortform".';
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => array_merge(DiviWriter::inputProperties(), [
+                'nodes' => [
+                    'type' => 'array',
+                    'minItems' => 1,
+                    'maxItems' => 20,
+                    'items' => ['type' => 'object'],
+                    'description' => 'Einzufügende Knoten in Reihenfolge; Abschnitte mit rows/modules, Zeilen mit '
+                        . 'columns und modules, Module mit Kurzform-Feldern, items (Kind-Module) und attrs.',
+                ],
+            ], DiviWriter::positionProperties()),
+            'required' => ['post_id', 'tree_rev', 'nodes'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function outputSchema(): ?array
+    {
+        return ToolResult::schema(['tree_rev' => ['type' => 'string']], ['tree_rev']);
+    }
+
+    public function annotations(): array
+    {
+        return ['readonly' => false, 'destructive' => false, 'idempotent' => false];
+    }
+
+    public function isDirect(): bool
+    {
+        return true;
+    }
+
+    public function permission(array $input): bool|WP_Error
+    {
+        $page = $this->writer->page($input);
+
+        return $page instanceof WP_Error ? $page : true;
+    }
+
+    public function execute(array $input): mixed
+    {
+        $page = $this->writer->page($input);
+        if ($page instanceof WP_Error) {
+            return $page;
+        }
+
+        $composition = $this->writer->composition($page);
+        $editor = $composition->editor();
+        $position = $editor->position($page->index, $input);
+        if (is_string($position)) {
+            // The nodes are checked against their parent – without a valid position there is none.
+            return Errors::invalidInput('Ungültige Position; nichts wurde gespeichert.', ['position' => $position]);
+        }
+
+        $context = DiviWriter::sectionLabel($page->index, $position['parent']);
+        $nodes = is_array($input['nodes'] ?? null) ? array_values($input['nodes']) : [];
+        if ($nodes === []) {
+            return Errors::invalidInput('Keine Knoten angegeben; nichts wurde gespeichert.', [
+                'nodes' => 'mindestens ein Knoten',
+            ]);
+        }
+
+        $composed = $composition->composer()->compose($nodes, $position['parent'], 'nodes', $context);
+        if ($composed['errors'] !== []) {
+            return $composed['invalid_paths'] !== []
+                ? Errors::invalidAttrPath($composed['errors'])
+                : Errors::invalidInput('Knoten sind ungültig; nichts wurde gespeichert.', $composed['errors']);
+        }
+
+        $violation = $editor->insert($position, $composed['blocks']);
+        if ($violation !== null) {
+            return Errors::invalidInput(
+                'Knoten passen nicht an diese Stelle; nichts wurde gespeichert.',
+                ['nodes' => $violation]
+            );
+        }
+
+        $change = new DiviChange(sprintf('%d Divi-Knoten eingefügt', count($composed['blocks'])));
+        foreach ($composed['blocks'] as $block) {
+            $change->changed($block, 'inserted');
+        }
+
+        return $this->writer->save($this->name(), $page, $change, $input);
+    }
+}

src/Integrations/Divi/Pages/DiviUpdateAbility.php

@@ -0,0 +1,175 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations\Divi\Pages;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\Errors;
+use LIT\MCP\Abilities\ToolResult;
+use LIT\MCP\Integrations\Divi\BlockTree\Block;
+use WP_Error;
+
+/**
+ * lit/divi-update: sets or removes values of existing nodes – short-form fields ("set"), full
+ * form ("attrs", null removes a path or breakpoint), preset and admin label (spec §5.7). Several
+ * nodes per call, all or nothing (ruling S39): every change is validated first and all errors
+ * come back together; only then are the attributes Composer::update() computed set. A node may
+ * appear once per call (ruling S14); set and attrs of one change must not reach the same path
+ * (ruling S38, checked by Composer::update()).
+ */
+final class DiviUpdateAbility implements Ability
+{
+    public function __construct(private DiviWriter $writer)
+    {
+    }
+
+    public function name(): string
+    {
+        return 'lit/divi-update';
+    }
+
+    public function label(): string
+    {
+        return 'Divi-Knoten ändern';
+    }
+
+    public function description(): string
+    {
+        return 'Ändert vorhandene Divi-Knoten: changes = Liste von {id, set: {Kurzform-Felder}, attrs: {Attributpfad: '
+            . '{Breakpoint: Wert}}, preset, label}. null entfernt einen Wert. Nicht genannte Einstellungen bleiben '
+            . 'unverändert. Jeder Knoten nur einmal pro Aufruf; denselben Pfad nicht zugleich über set und attrs. '
+            . 'tree_rev aus lit-divi-outline ist Pflicht; alles oder nichts.';
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => array_merge(DiviWriter::inputProperties(), [
+                'changes' => [
+                    'type' => 'array',
+                    'minItems' => 1,
+                    'maxItems' => 50,
+                    'items' => [
+                        'type' => 'object',
+                        'properties' => [
+                            'id' => ['type' => 'string'],
+                            'set' => ['type' => 'object', 'description' => 'Kurzform-Felder, z. B. {"text": "Neu"}.'],
+                            'attrs' => [
+                                'type' => 'object',
+                                'description' => 'Vollform: Attributpfad → Breakpoint-Werte.',
+                            ],
+                            'preset' => ['type' => ['string', 'null'], 'description' => 'Preset-Name; null entfernt.'],
+                            'label' => [
+                                'type' => ['string', 'null'],
+                                'description' => 'Admin-Label im Divi-Builder; null entfernt.',
+                            ],
+                        ],
+                        'required' => ['id'],
+                        'additionalProperties' => false,
+                    ],
+                ],
+            ]),
+            'required' => ['post_id', 'tree_rev', 'changes'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function outputSchema(): ?array
+    {
+        return ToolResult::schema(['tree_rev' => ['type' => 'string']], ['tree_rev']);
+    }
+
+    public function annotations(): array
+    {
+        return ['readonly' => false, 'destructive' => false, 'idempotent' => true];
+    }
+
+    public function isDirect(): bool
+    {
+        return true;
+    }
+
+    public function permission(array $input): bool|WP_Error
+    {
+        $page = $this->writer->page($input);
+
+        return $page instanceof WP_Error ? $page : true;
+    }
+
+    public function execute(array $input): mixed
+    {
+        $page = $this->writer->page($input);
+        if ($page instanceof WP_Error) {
+            return $page;
+        }
+
+        $changes = is_array($input['changes'] ?? null) ? array_values($input['changes']) : [];
+        if ($changes === []) {
+            return Errors::invalidInput('Keine Änderungen angegeben; nichts wurde gespeichert.', [
+                'changes' => 'mindestens eine Änderung',
+            ]);
+        }
+
+        $composer = $this->writer->composition($page)->composer();
+        $errors = [];
+        $invalidPaths = false;
+        /** @var array<string, int> $seen id => position of its first change */
+        $seen = [];
+        /** @var list<array{0: Block, 1: array<string, mixed>}> $updates */
+        $updates = [];
+        foreach ($changes as $position => $change) {
+            $field = sprintf('changes[%d]', $position);
+            if (! is_array($change)) {
+                $errors[$field] = 'Objekt mit id erwartet';
+                continue;
+            }
+
+            $id = is_string($change['id'] ?? null) ? $change['id'] : '';
+            if ($id !== '' && isset($seen[$id])) {
+                // Ruling S14: a second change of the same node would overwrite the first silently.
+                $errors[$field . '.id'] = sprintf(
+                    'Knoten "%s" steht schon in changes[%d]; alle Änderungen eines Knotens in einer Änderung bündeln',
+                    $id,
+                    $seen[$id]
+                );
+                continue;
+            }
+
+            $block = $id === '' ? null : $page->index->find($id);
+            if ($id !== '') {
+                $seen[$id] = $position;
+            }
+
+            if ($block === null) {
+                $errors[$field . '.id'] = sprintf('Knoten "%s" gibt es nicht (lit-divi-outline neu lesen)', $id);
+                continue;
+            }
+
+            $result = $composer->update($block, $change, $field);
+            $errors += $result['errors'];
+            $invalidPaths = $invalidPaths || $result['invalid_paths'] !== [];
+            $updates[] = [$block, $result['attrs']];
+        }
+
+        if ($errors !== []) {
+            return $invalidPaths
+                ? Errors::invalidAttrPath($errors)
+                : Errors::invalidInput('Änderungen sind ungültig; nichts wurde gespeichert.', $errors);
+        }
+
+        $updates = array_values(array_filter(
+            $updates,
+            static fn (array $update): bool => $update[1] !== $update[0]->attrs()
+        ));
+        $change = new DiviChange(sprintf('%d Divi-Knoten geändert', count($updates)));
+        foreach ($updates as [$block, $attrs]) {
+            // Composer::update() output: every client value already passed the choke point.
+            $block->setAttrs($attrs);
+            $change->changed($block, 'updated');
+        }
+
+        return $this->writer->save($this->name(), $page, $change, $input);
+    }
+}

src/Plugin.php

@@ -68,7 +68,7 @@ final class Plugin
             new CoreIntegration(self::pluginDir() . '/docs/guides'),
             new WordPressIntegration($schema, $changeLog),
             new MediaIntegration($schema, $changeLog, $limits),
-            new DiviIntegration($schema)
+            new DiviIntegration($schema, $changeLog)
         );
 
         $policy = ExposurePolicy::fromOption();