@wootsup/yt-builder-mcp 1.1.6 → 1.1.7

package/dist/tools/inspection.js

@@ -0,0 +1,208 @@
+/**
+ * Element-type inspection tools.
+ *
+ *   yootheme_builder_element_types_list
+ *      → catalogue of available element types (tableResult — Wave G.2)
+ *   yootheme_builder_element_type_get_schema
+ *      → field schema for a single element type (detailResult — Wave G.2)
+ *
+ * @license MIT
+ */
+import { detailResult, tableResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { TYPES_COMPACT_COLUMNS, TYPES_TABLE_COLUMNS, buildTypeSchemaDetail, flattenTypesPayload, mapTypeRow, } from './format/inspection-format.js';
+import { SITE_ID_SCHEMA } from './shared-schemas.js';
+import { resolveSiteOrError } from './pool-resolve-helper.js';
+import { defineTool, errorResult, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
+import { DEFAULT_FIELDS_TYPES_LIST, FIELDS, projectFields, projectedFieldsEcho, projectionFeedback, } from './sparse-fields.js';
+// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+const TYPES_LIST_OUTPUT_SCHEMA = z.object({
+    items: z.array(z.record(z.string(), z.unknown())),
+    total: z.number(),
+    projected_fields: z.array(z.string()).optional(),
+    // F-004 fix (2026-05-25 exhaustive audit): see sparse-fields::projectionFeedback.
+    available_fields: z.array(z.string()).optional(),
+    unknown_fields: z.array(z.string()).optional(),
+});
+const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
+    name: z.string(),
+    label: z.string().optional(),
+    origin: z.string().optional(),
+    // The REST endpoint returns `fields` as a list of {name,type,label?}
+    // field descriptors — each `name` is a valid prop key for element_add /
+    // _update_settings.
+    fields: z.array(z.record(z.string(), z.unknown())).optional(),
+    field_count: z.number(),
+});
+export function buildInspectionTools(pool) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_element_types_list',
+            description: 'List element types registered on this site (built-ins + ' +
+                'YOOessentials/uEssentials extras). Names feed `element_type` of ' +
+                'element_add. Pass `fields[]` to narrow each row. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                fields: FIELDS,
+            },
+            outputSchema: TYPES_LIST_OUTPUT_SCHEMA,
+            annotations: readOnly('List Element Types'),
+            handler: async ({ site_id, fields }) => {
+                const r = await resolveSiteOrError(pool, site_id);
+                if (!r.ok)
+                    return r.error;
+                const { client: siteClient, site } = r;
+                try {
+                    const data = await siteClient.get('/element-types');
+                    const flat = flattenTypesPayload(data);
+                    const mapped = flat.map(mapTypeRow);
+                    const mappedRecords = mapped;
+                    const items = projectFields(mappedRecords, fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const feedback = projectionFeedback(mappedRecords, fields);
+                    const unknownNote = feedback !== undefined && feedback.unknown_fields.length > 0
+                        ? ` (unknown fields ignored: ${feedback.unknown_fields.join(', ')}; available: ${feedback.available_fields.join(', ')})`
+                        : '';
+                    const toolkitResult = tableResult(mappedRecords, {
+                        columns: [...TYPES_TABLE_COLUMNS],
+                        compactColumns: [...TYPES_COMPACT_COLUMNS],
+                        header: (count) => `${String(count)} element types${unknownNote}`,
+                        footer: 'Use yootheme_builder_element_type_get_schema <name> for fields.',
+                    });
+                    return withSiteMeta(structuredResult(toolkitResult, {
+                        items,
+                        total: items.length,
+                        ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
+                        ...(feedback !== undefined ? {
+                            available_fields: [...feedback.available_fields],
+                            unknown_fields: [...feedback.unknown_fields],
+                        } : {}),
+                    }), site);
+                }
+                catch (e) {
+                    return withSiteMeta(errorResult({
+                        error: e,
+                        context: { site_id: site.id },
+                        hint: 'Run yootheme_builder_diagnose to verify auth.',
+                    }), site);
+                }
+            },
+        }),
+        buildElementTypeGetSchemaTool(pool),
+    ];
+}
+/**
+ * F-203 follow-up (Audit 2026-05-26 reviewer Gap 2): factored out of
+ * `buildInspectionTools` so the shape + refined ZodObject pair lives in
+ * one place. The SDK's pre-handler validator honours the top-level
+ * `.refine()` on `TYPE_SCHEMA_REFINED` and raises
+ * JSON-RPC `-32602 InvalidParams` when violated — hosts see the
+ * failure BEFORE the handler ever runs. The raw shape stays for
+ * handler-type inference (see `inputSchema`).
+ */
+function buildElementTypeGetSchemaTool(pool) {
+    const TYPE_SCHEMA_SHAPE = {
+        site_id: SITE_ID_SCHEMA,
+        // 1.0.1 cross-tool parameter naming alignment: every other
+        // tool in this domain uses `element_type` (element_add,
+        // element_update_settings, element_list rows). This tool
+        // originally shipped with `type_name`; we accept BOTH for
+        // backward-compatibility but the canonical key going
+        // forward is `element_type`.
+        element_type: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Element type name (e.g. "headline", "text", "grid"). Use ' +
+            'yootheme_builder_element_types_list to discover.'),
+        type_name: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('DEPRECATED alias of `element_type` — use `element_type` ' +
+            'instead. Kept for 1.0.x backward-compatibility; will be ' +
+            'removed in a future major.'),
+    };
+    const TYPE_SCHEMA_REFINED = z
+        .object(TYPE_SCHEMA_SHAPE)
+        .refine((args) => (typeof args.element_type === 'string' && args.element_type !== '') ||
+        (typeof args.type_name === 'string' && args.type_name !== ''), {
+        message: 'Provide either `element_type` (canonical) or ' +
+            '`type_name` (deprecated alias).',
+    });
+    return defineTool({
+        name: 'yootheme_builder_element_type_get_schema',
+        description: '**Call before every `element_add` / `_update_settings`** — unknown ' +
+            'prop keys are silently dropped server-side, so guessing fails ' +
+            'quietly. Returns `{name,type,label?}` field descriptors. Use ' +
+            '`element_type`; `type_name` is DEPRECATED. ' +
+            'Operates on the default site unless site_id is provided.',
+        inputSchema: TYPE_SCHEMA_SHAPE,
+        // F-203 follow-up: the refined object is what the SDK actually
+        // validates. The raw shape above stays for handler-type inference.
+        inputObjectSchema: TYPE_SCHEMA_REFINED,
+        outputSchema: TYPE_SCHEMA_OUTPUT_SCHEMA,
+        annotations: readOnly('Get Element Type Schema'),
+        handler: async (args) => {
+            // Defensive re-assert of the refine — should never fire when
+            // reached through the SDK (the boundary rejects with -32602
+            // first), but in-process tests bypass the SDK and call the
+            // handler directly, so the structured error path stays
+            // reachable for unit-test coverage.
+            const typeNameInput = typeof args.element_type === 'string' && args.element_type !== ''
+                ? args.element_type
+                : typeof args.type_name === 'string'
+                    ? args.type_name
+                    : '';
+            if (typeNameInput === '') {
+                return errorResult({
+                    error: new Error('Provide either `element_type` (canonical) or ' +
+                        '`type_name` (deprecated alias).'),
+                    context: { site_id: typeof args.site_id === 'string' ? args.site_id : null },
+                    hint: 'Pass `element_type` (e.g. "headline"). Use ' +
+                        'yootheme_builder_element_types_list to discover valid values.',
+                });
+            }
+            const type_name = typeNameInput;
+            const r = await resolveSiteOrError(pool, typeof args.site_id === 'string' ? args.site_id : undefined);
+            if (!r.ok)
+                return r.error;
+            const { client: siteClient, site } = r;
+            try {
+                const data = await siteClient.get(`/element-types/${encodeURIComponent(type_name)}/schema`);
+                // The REST endpoint nests the type schema under `schema`:
+                // {type_name, schema:{name,label,origin,has_children,fields:[…]}}.
+                // Fall back to the top-level object for older backends.
+                const schema = data.schema !== null && typeof data.schema === 'object'
+                    ? data.schema
+                    : data;
+                const name = typeof schema.name === 'string' ? schema.name : type_name;
+                const label = typeof schema.label === 'string' ? schema.label : undefined;
+                const origin = typeof schema.origin === 'string' ? schema.origin : undefined;
+                // `fields` is a list of {name,type,label?} field descriptors.
+                const fields = Array.isArray(schema.fields)
+                    ? schema.fields
+                    : undefined;
+                const fieldCount = fields !== undefined ? fields.length : 0;
+                const toolkitResult = detailResult(buildTypeSchemaDetail({ name, label, origin, fields }));
+                return withSiteMeta(structuredResult(toolkitResult, {
+                    name,
+                    ...(label !== undefined ? { label } : {}),
+                    ...(origin !== undefined ? { origin } : {}),
+                    ...(fields !== undefined ? { fields } : {}),
+                    field_count: fieldCount,
+                }), site);
+            }
+            catch (e) {
+                return withSiteMeta(errorResult({
+                    error: e,
+                    context: { element_type: type_name, site_id: site.id },
+                    hint: 'Verify element_type via yootheme_builder_element_types_list — names ' +
+                        'are case-sensitive.',
+                }), site);
+            }
+        },
+    });
+}
+//# sourceMappingURL=inspection.js.map

package/dist/tools/inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.js","sourceRoot":"","sources":["../../src/tools/inspection.ts"],"names":[],"mappings":"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"}

package/dist/tools/layout-flatten.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Layout-flatten helper — depth-first walk that turns a nested YOOtheme
+ * layout tree into a flat array of `{ path, parent_path, depth,
+ * element_type, props }` records.
+ *
+ * Used by `yootheme_builder_page_get_layout` when called with
+ * `flat: true`. Per Design §4.4.1:
+ *
+ *   - Walk-order: depth-first, parent BEFORE children, original child
+ *     order preserved (no sort).
+ *   - `path` uses JSON-Pointer-style notation rooted at `/layout/<key>`
+ *     and descends via `/children/<index>` segments. The root segments
+ *     mirror the keys the REST plugin produces (string keys "0","1",…
+ *     when the top-level layout is an object; numeric indices when it
+ *     happens to be an array).
+ *   - `parent_path` is `null` for top-level entries.
+ *   - The emitted record's `children` field is REMOVED — children become
+ *     their own emitted entries with their own `path`. Keeping the nested
+ *     array would defeat the purpose of flattening.
+ *   - Non-object children are skipped silently but their index is
+ *     preserved in the parent's child-numbering (the next valid sibling
+ *     keeps its original index).
+ *
+ * Pure function — no I/O, no client dependency. Test-covered in
+ * `tests/tools/layout-flatten.test.ts`.
+ *
+ * @license MIT
+ */
+/** A single emitted record in the flattened layout. */
+export interface FlatElement {
+    /** JSON-Pointer-style path, e.g. "/layout/0/children/2". */
+    path: string;
+    /**
+     * Path with the `/layout` prefix stripped, e.g. "/0/children/2".
+     * N-01 (Audit v4): mirrors the `rel_path` column element_list emits
+     * so `fields:["rel_path",...]` projection works on the flat layout.
+     */
+    rel_path: string;
+    /** Path of the parent element, or `null` for top-level entries. */
+    parent_path: string | null;
+    /** 0-based depth (top-level entries have depth 0). */
+    depth: number;
+    /** Element type string (the `type` field on the YT node, "" if missing). */
+    element_type: string;
+    /**
+     * True iff the node carries a source-binding. N-01 (Audit v4):
+     * derived via the same `hasSourceBinding` SSoT element_list uses,
+     * or an explicit REST-plugin boolean when present.
+     */
+    has_binding: boolean;
+    /** Element props (passthrough; `undefined` when the node has none). */
+    props?: Record<string, unknown>;
+    /**
+     * Children intentionally absent — see file-header. Kept in the type
+     * so consumers can confirm the field is `undefined` rather than
+     * assume it exists.
+     */
+    children?: undefined;
+    /**
+     * Allow passthrough of any other top-level fields the REST plugin
+     * may add in future (e.g. `label`, `has_binding`, `name`). The
+     * walker preserves these verbatim so projection via `pickFields`
+     * downstream stays meaningful.
+     */
+    [extra: string]: unknown;
+}
+/**
+ * Flatten a YOOtheme nested layout tree.
+ *
+ * @param layout - The top-level layout container. Accepts either an
+ *   object keyed by stringified indices ("0","1",…) or an actual array.
+ *   Returns `[]` for empty input or anything that isn't iterable.
+ */
+export declare function flattenLayout(layout: unknown): FlatElement[];
+//# sourceMappingURL=layout-flatten.d.ts.map

package/dist/tools/layout-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-flatten.d.ts","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAmB5D"}

package/dist/tools/layout-flatten.js

@@ -0,0 +1,107 @@
+/**
+ * Layout-flatten helper — depth-first walk that turns a nested YOOtheme
+ * layout tree into a flat array of `{ path, parent_path, depth,
+ * element_type, props }` records.
+ *
+ * Used by `yootheme_builder_page_get_layout` when called with
+ * `flat: true`. Per Design §4.4.1:
+ *
+ *   - Walk-order: depth-first, parent BEFORE children, original child
+ *     order preserved (no sort).
+ *   - `path` uses JSON-Pointer-style notation rooted at `/layout/<key>`
+ *     and descends via `/children/<index>` segments. The root segments
+ *     mirror the keys the REST plugin produces (string keys "0","1",…
+ *     when the top-level layout is an object; numeric indices when it
+ *     happens to be an array).
+ *   - `parent_path` is `null` for top-level entries.
+ *   - The emitted record's `children` field is REMOVED — children become
+ *     their own emitted entries with their own `path`. Keeping the nested
+ *     array would defeat the purpose of flattening.
+ *   - Non-object children are skipped silently but their index is
+ *     preserved in the parent's child-numbering (the next valid sibling
+ *     keeps its original index).
+ *
+ * Pure function — no I/O, no client dependency. Test-covered in
+ * `tests/tools/layout-flatten.test.ts`.
+ *
+ * @license MIT
+ */
+import { hasSourceBinding } from './format/elements-format.js';
+/**
+ * Flatten a YOOtheme nested layout tree.
+ *
+ * @param layout - The top-level layout container. Accepts either an
+ *   object keyed by stringified indices ("0","1",…) or an actual array.
+ *   Returns `[]` for empty input or anything that isn't iterable.
+ */
+export function flattenLayout(layout) {
+    const out = [];
+    if (layout === null || typeof layout !== 'object') {
+        return out;
+    }
+    // Iterate top-level entries in insertion order. For arrays this gives
+    // numeric indices; for objects keyed by "0","1",… it gives the same
+    // ordering YT serialises.
+    const entries = Array.isArray(layout)
+        ? layout.map((v, i) => [String(i), v])
+        : Object.entries(layout);
+    for (const [key, node] of entries) {
+        walk(node, `/layout/${key}`, null, 0, out);
+    }
+    return out;
+}
+/**
+ * Depth-first walker. Emits the node, then recurses into its children.
+ * Skips non-object nodes silently while preserving child-index numbering.
+ */
+function walk(node, path, parentPath, depth, out) {
+    if (node === null || typeof node !== 'object' || Array.isArray(node)) {
+        return;
+    }
+    const obj = node;
+    const elementType = typeof obj.type === 'string' ? obj.type : '';
+    const props = obj.props !== null && typeof obj.props === 'object' && !Array.isArray(obj.props)
+        ? obj.props
+        : undefined;
+    // N-01: derive the projection-relevant fields up-front so a
+    // `fields:["rel_path","has_binding",...]` projection finds them.
+    // `rel_path` strips the `/layout` prefix; `has_binding` honours an
+    // explicit REST boolean else derives via the shared SSoT.
+    const relPath = path.replace(/^\/layout/, '') || '/';
+    const hasBinding = typeof obj.has_binding === 'boolean'
+        ? obj.has_binding
+        : hasSourceBinding(obj);
+    // Build a passthrough shallow-clone WITHOUT the children field. We
+    // copy every other top-level key so future REST additions (label,
+    // …) survive the flatten.
+    const emitted = {
+        path,
+        rel_path: relPath,
+        parent_path: parentPath,
+        depth,
+        element_type: elementType,
+        has_binding: hasBinding,
+    };
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === 'children' || k === 'type' || k === 'props' || k === 'has_binding') {
+            continue;
+        }
+        emitted[k] = v;
+    }
+    if (props !== undefined)
+        emitted.props = props;
+    out.push(emitted);
+    const children = obj.children;
+    if (Array.isArray(children)) {
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            if (child === null || typeof child !== 'object' || Array.isArray(child)) {
+                // Skip non-object children; their index is preserved in
+                // the next sibling's path.
+                continue;
+            }
+            walk(child, `${path}/children/${String(i)}`, path, depth + 1, out);
+        }
+    }
+}
+//# sourceMappingURL=layout-flatten.js.map

package/dist/tools/layout-flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-flatten.js","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"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"}

package/dist/tools/multi-items/builders.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Multi-Items tool builders.
+ *
+ * Surfaces two tools that operate on the YT-Pro Multi-Items binding
+ * pattern (container ↔ `*_item` pairings — see
+ * `./item-container-map.ts`):
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Reports the binding level (none/container/item), the matching
+ *       container/item pair, and whether legacy implode directives are
+ *       attached. Surfaces a `recommended_fix` when the binding sits on
+ *       the container level.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Removes every `props.source.props.*.implode` directive from
+ *       the addressed element. Returns the audit log + new etag.
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../../sites/client-pool.js';
+import { type AnyToolDefinition } from '../tool-builder.js';
+export declare function buildMultiItemsTools(pool: ClientPool): readonly AnyToolDefinition[];
+//# sourceMappingURL=builders.d.ts.map

package/dist/tools/multi-items/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAW5B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA0DnF"}

package/dist/tools/multi-items/builders.js

@@ -0,0 +1,78 @@
+/**
+ * Multi-Items tool builders.
+ *
+ * Surfaces two tools that operate on the YT-Pro Multi-Items binding
+ * pattern (container ↔ `*_item` pairings — see
+ * `./item-container-map.ts`):
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Reports the binding level (none/container/item), the matching
+ *       container/item pair, and whether legacy implode directives are
+ *       attached. Surfaces a `recommended_fix` when the binding sits on
+ *       the container level.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Removes every `props.source.props.*.implode` directive from
+ *       the addressed element. Returns the audit log + new etag.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { withSiteRetry } from '../pool-resolve-helper.js';
+import { ELEMENT_PATH, ETAG, SITE_ID_SCHEMA, TEMPLATE_ID } from '../shared-schemas.js';
+import { defineTool, destructive, readOnly, withSiteMeta, } from '../tool-builder.js';
+import { CLEAN_IMPLODE_OUTPUT_SCHEMA, handleCleanImplodeDirectives, } from './clean-implode-handler.js';
+import { INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA, handleInspectMultiItemsBinding, } from './inspect-handler.js';
+export function buildMultiItemsTools(pool) {
+    // W6.3 — per-handler resolveSiteOrError. The handlers consume a
+    // single-field `MultiItemsHandlerDeps`, so we synthesise it inline
+    // with the resolved client.
+    return [
+        defineTool({
+            name: 'yootheme_builder_inspect_multi_items_binding',
+            description: 'Reports Multi-Items binding state: container/item pair (grid↔grid_item, ' +
+                'slideshow↔slideshow_item, …), current binding level (none|container|item), ' +
+                'and a recommended_fix when the binding sits on the container instead of the child. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                element_path: ELEMENT_PATH,
+            },
+            outputSchema: INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA,
+            annotations: readOnly('Inspect Multi-Items Binding'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => {
+                const deps = { client };
+                return withSiteMeta(await handleInspectMultiItemsBinding(deps, rest), site);
+            }),
+        }),
+        defineTool({
+            name: 'yootheme_builder_clean_implode_directives',
+            description: 'Strips `props.source.props.*.implode` directives from an element binding. ' +
+                'Returns audit log + new ETag. Idempotent at the server (cleaned_count: 0 ' +
+                'when nothing to remove) but classed as destructive because the affected ' +
+                'binding cannot be restored without re-mapping. Always ask the user to ' +
+                'confirm first, then call again with `confirm: true`. Requires ETag. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                element_path: ELEMENT_PATH,
+                etag: ETAG,
+                confirm: z
+                    .boolean()
+                    .optional()
+                    .describe('Must be true to execute. Without it the call returns a preview ' +
+                    'and makes NO server-side change; the agent must ask the user ' +
+                    'to confirm and retry with `confirm: true`.'),
+            },
+            outputSchema: CLEAN_IMPLODE_OUTPUT_SCHEMA,
+            annotations: destructive('Clean Implode Directives'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => {
+                const deps = { client };
+                return withSiteMeta(await handleCleanImplodeDirectives(deps, rest), site);
+            }),
+        }),
+    ];
+}
+//# sourceMappingURL=builders.js.map

package/dist/tools/multi-items/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EACH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,4BAA4B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,iCAAiC,EACjC,8BAA8B,GAEjC,MAAM,sBAAsB,CAAC;AAE9B,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,gEAAgE;IAChE,mEAAmE;IACnE,4BAA4B;IAC5B,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,8CAA8C;YACpD,WAAW,EACP,0EAA0E;gBAC1E,6EAA6E;gBAC7E,qFAAqF;gBACrF,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,iCAAiC;YAC/C,WAAW,EAAE,QAAQ,CAAC,6BAA6B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,8BAA8B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAChF,CAAC,CAAC;SACT,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2CAA2C;YACjD,WAAW,EACP,4EAA4E;gBAC5E,2EAA2E;gBAC3E,0EAA0E;gBAC1E,wEAAwE;gBACxE,sEAAsE;gBACtE,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;gBAC1B,IAAI,EAAE,IAAI;gBACV,OAAO,EAAE,CAAC;qBACL,OAAO,EAAE;qBACT,QAAQ,EAAE;qBACV,QAAQ,CACL,iEAAiE;oBAC7D,+DAA+D;oBAC/D,4CAA4C,CACnD;aACR;YACD,YAAY,EAAE,2BAA2B;YACzC,WAAW,EAAE,WAAW,CAAC,0BAA0B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,4BAA4B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC9E,CAAC,CAAC;SACT,CAAC;KACL,CAAC;AACN,CAAC"}

package/dist/tools/multi-items/clean-implode-handler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `clean_implode_directives` handler — strip `props.source.props.*.implode`
+ * directives from an element binding via REST round-trip.
+ *
+ * Wave H5 (2026-05-26): destructive confirm-guard. The tool is now
+ * registered with `destructive()` annotation (was `mutating()`); per the
+ * MCP Goldstandard, every destructive tool MUST also expose a `confirm`
+ * input field + preview guard so an auto-acting agent cannot strip
+ * implode directives from a binding without an explicit second gate.
+ * Mirrors the `element_delete` pattern (handlers-write.ts).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { type RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+export declare const CLEAN_IMPLODE_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    element_path: z.ZodString;
+    cleaned_count: z.ZodNumber;
+    removed_directives: z.ZodArray<z.ZodObject<{
+        prop_name: z.ZodString;
+        directive: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    new_etag: z.ZodString;
+}, z.core.$strip>;
+export interface CleanImplodeHandlerDeps {
+    readonly client: RestClient;
+}
+export declare function handleCleanImplodeDirectives({ client }: CleanImplodeHandlerDeps, { template_id, element_path, etag, confirm, }: {
+    template_id: string;
+    element_path: string;
+    etag: string;
+    confirm?: boolean;
+}): Promise<ToolResult>;
+//# sourceMappingURL=clean-implode-handler.d.ts.map

package/dist/tools/multi-items/clean-implode-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-implode-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B;;;;;;;;;iBAWtC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,4BAA4B,CAC9C,EAAE,MAAM,EAAE,EAAE,uBAAuB,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GACV,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,GACF,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/tools/multi-items/clean-implode-handler.js

@@ -0,0 +1,57 @@
+/**
+ * `clean_implode_directives` handler — strip `props.source.props.*.implode`
+ * directives from an element binding via REST round-trip.
+ *
+ * Wave H5 (2026-05-26): destructive confirm-guard. The tool is now
+ * registered with `destructive()` annotation (was `mutating()`); per the
+ * MCP Goldstandard, every destructive tool MUST also expose a `confirm`
+ * input field + preview guard so an auto-acting agent cannot strip
+ * implode directives from a binding without an explicit second gate.
+ * Mirrors the `element_delete` pattern (handlers-write.ts).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { encodeElementPath } from '../../client.js';
+import { confirmGuard, errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
+export const CLEAN_IMPLODE_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    element_path: z.string(),
+    cleaned_count: z.number(),
+    removed_directives: z.array(z.object({
+        prop_name: z.string(),
+        directive: z.record(z.string(), z.unknown()),
+    })),
+    new_etag: z.string(),
+});
+export async function handleCleanImplodeDirectives({ client }, { template_id, element_path, etag, confirm, }) {
+    // Wave H5 confirm-guard. Without `confirm: true` we return a preview
+    // payload and make NO HTTP call. The preview surfaces enough context
+    // (template + element_path + operation) for the host agent to ask the
+    // user to confirm. Symmetric with `element_delete` / `element_unbind_source`.
+    if (confirm !== true) {
+        return confirmGuard({
+            operation: 'strip implode directives from element binding',
+            details: { template_id, element_path },
+        });
+    }
+    const encoded = encodeElementPath(element_path);
+    try {
+        const data = await client.post(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/multi-items/clean-implode`, { body: {}, etag });
+        // The REST endpoint returns the canonical CLEAN_IMPLODE_OUTPUT_SCHEMA
+        // shape ({template_id, element_path, cleaned_count, removed_directives,
+        // new_etag}) — pass it through as structuredContent so the declared
+        // outputSchema is satisfied (a tool with an outputSchema MUST emit
+        // structuredContent, else the MCP SDK rejects with -32602).
+        return structuredResult(jsonResult(data), data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, element_path },
+            hint: 'On 412 refresh via yootheme_builder_get_etag and retry. On 404 verify the ' +
+                'element_path via yootheme_builder_element_list.',
+        });
+    }
+}
+//# sourceMappingURL=clean-implode-handler.js.map

package/dist/tools/multi-items/clean-implode-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-implode-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,kBAAkB,EAAE,CAAC,CAAC,KAAK,CACvB,CAAC,CAAC,MAAM,CAAC;QACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC,CACL;IACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAC9C,EAAE,MAAM,EAA2B,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GAMV;IAED,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,8EAA8E;IAC9E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC;YAChB,SAAS,EAAE,+CAA+C;YAC1D,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;SACzC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACzF,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CACrB,CAAC;QACF,sEAAsE;QACtE,wEAAwE;QACxE,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,4EAA4E;gBAC5E,iDAAiD;SACxD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}