@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

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

@@ -0,0 +1,84 @@
+/**
+ * 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';
+import { InspectionCache } from './inspection-cache.js';
+export function buildMultiItemsTools(pool) {
+    // 6.2 — one shared inspection cache per tool-build, keyed on
+    // (template_id, element_path, global-etag) with a 60s TTL. Survives
+    // across calls within a server lifetime; a write bumps the global
+    // etag and naturally invalidates the entry.
+    const inspectionCache = new InspectionCache();
+    // 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, cache: inspectionCache };
+                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;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,6DAA6D;IAC7D,oEAAoE;IACpE,kEAAkE;IAClE,4CAA4C;IAC5C,MAAM,eAAe,GAAG,IAAI,eAAe,EAA2B,CAAC;IAEvE,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,KAAK,EAAE,eAAe,EAAE,CAAC;gBACvE,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,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,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, encodeTemplateId } 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/${encodeTemplateId(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,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACvF,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,gBAAgB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACvF,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"}

package/dist/tools/multi-items/format/inspection-format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export declare const MAX_INSPECTION_DEPTH = 3;
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export declare function capInspectionDepth(value: unknown, maxDepth?: number, depth?: number): unknown;
+//# sourceMappingURL=inspection-format.d.ts.map

package/dist/tools/multi-items/format/inspection-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.d.ts","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAYtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAA6B,EACvC,KAAK,SAAI,GACV,OAAO,CAeT"}

package/dist/tools/multi-items/format/inspection-format.js

@@ -0,0 +1,64 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export const MAX_INSPECTION_DEPTH = 3;
+/** Render the marker that replaces a truncated subtree. */
+function truncationMarker(childCount, maxDepth) {
+    return `…and ${String(childCount)} more (truncated at depth ${String(maxDepth)})`;
+}
+/** Number of immediate children an object/array exposes. */
+function childCountOf(value) {
+    return Array.isArray(value) ? value.length : Object.keys(value).length;
+}
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export function capInspectionDepth(value, maxDepth = MAX_INSPECTION_DEPTH, depth = 0) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth >= maxDepth) {
+        return truncationMarker(childCountOf(value), maxDepth);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => capInspectionDepth(item, maxDepth, depth + 1));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = capInspectionDepth(child, maxDepth, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=inspection-format.js.map

package/dist/tools/multi-items/format/inspection-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.js","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,2DAA2D;AAC3D,SAAS,gBAAgB,CAAC,UAAkB,EAAE,QAAgB;IAC1D,OAAO,QAAQ,MAAM,CAAC,UAAU,CAAC,6BAA6B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;AACtF,CAAC;AAED,4DAA4D;AAC5D,SAAS,YAAY,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAC9B,KAAc,EACd,WAAmB,oBAAoB,EACvC,KAAK,GAAG,CAAC;IAET,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACpB,OAAO,gBAAgB,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Multi-Items tool barrel — public entry-point for the YT-Pro
+ * Multi-Items binding pattern tools.
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Report the Multi-Items binding state for an element.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Remove legacy implode directives from an element binding.
+ *
+ * The canonical container ↔ item map lives in `./item-container-map.ts`
+ * (mirror of `WootsUp\BuilderMcp\Elements\ItemContainerMap`).
+ *
+ * @license MIT
+ */
+export { buildMultiItemsTools } from './builders.js';
+export { ITEM_CHILDREN_OF_CONTAINER, containerOf, isContainer, isItem, itemOf, } from './item-container-map.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACH,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,MAAM,EACN,MAAM,GACT,MAAM,yBAAyB,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Multi-Items tool barrel — public entry-point for the YT-Pro
+ * Multi-Items binding pattern tools.
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Report the Multi-Items binding state for an element.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Remove legacy implode directives from an element binding.
+ *
+ * The canonical container ↔ item map lives in `./item-container-map.ts`
+ * (mirror of `WootsUp\BuilderMcp\Elements\ItemContainerMap`).
+ *
+ * @license MIT
+ */
+export { buildMultiItemsTools } from './builders.js';
+export { ITEM_CHILDREN_OF_CONTAINER, containerOf, isContainer, isItem, itemOf, } from './item-container-map.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/multi-items/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACH,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,MAAM,EACN,MAAM,GACT,MAAM,yBAAyB,CAAC"}

package/dist/tools/multi-items/inspect-handler.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `inspect_multi_items_binding` handler — surfaces Multi-Items binding
+ * state on an element via REST round-trip.
+ *
+ * Companion of the PHP `MultiItemsInspector` — see
+ * src/modules/builder-source-binding/src/MultiItemsInspector.php
+ * for the report shape.
+ *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { type RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+import { InspectionCache } from './inspection-cache.js';
+/**
+ * Severity of the advisory hint the inspector attaches to every report.
+ * `blocking` means the binding is structurally wrong (sits on the
+ * container instead of the `*_item` child) and the rendered output will
+ * be broken until fixed; `advisory` is informational guidance.
+ */
+export type HintSeverity = 'advisory' | 'blocking';
+export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    report: z.ZodObject<{
+        element_path: z.ZodString;
+        element_type: z.ZodString;
+        is_container: z.ZodBoolean;
+        is_item: z.ZodBoolean;
+        container_type: z.ZodNullable<z.ZodString>;
+        item_type: z.ZodNullable<z.ZodString>;
+        current_binding_level: z.ZodEnum<{
+            container: "container";
+            item: "item";
+            none: "none";
+        }>;
+        has_implode_directives: z.ZodBoolean;
+        warning: z.ZodOptional<z.ZodString>;
+        recommended_fix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    etag: z.ZodString;
+    hint: z.ZodOptional<z.ZodObject<{
+        severity: z.ZodEnum<{
+            advisory: "advisory";
+            blocking: "blocking";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The structured inspect payload the handler caches + emits. */
+type InspectStructured = Record<string, unknown>;
+export interface MultiItemsHandlerDeps {
+    readonly client: RestClient;
+    /**
+     * 6.2 — optional inspection cache. When provided, the handler keys
+     * results on (template_id, element_path, global-etag) with a 60s TTL.
+     * The builder injects one shared instance so repeat inspects within
+     * the TTL skip the REST round-trip; a write bumps the global etag and
+     * naturally invalidates the entry. Omit it to disable caching (e.g.
+     * the cold-AI shape-pin tests that assert the raw round-trip).
+     */
+    readonly cache?: InspectionCache<InspectStructured>;
+}
+export declare function handleInspectMultiItemsBinding({ client, cache }: MultiItemsHandlerDeps, { template_id, element_path }: {
+    template_id: string;
+    element_path: string;
+}): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=inspect-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwB5C,CAAC;AAEH,iEAAiE;AACjE,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACvD;AAoDD,wBAAsB,8BAA8B,CAChD,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,qBAAqB,EACxC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAwCrB"}

package/dist/tools/multi-items/inspect-handler.js

@@ -0,0 +1,133 @@
+/**
+ * `inspect_multi_items_binding` handler — surfaces Multi-Items binding
+ * state on an element via REST round-trip.
+ *
+ * Companion of the PHP `MultiItemsInspector` — see
+ * src/modules/builder-source-binding/src/MultiItemsInspector.php
+ * for the report shape.
+ *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
+import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
+import { capInspectionDepth } from './format/inspection-format.js';
+export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    report: z.object({
+        element_path: z.string(),
+        element_type: z.string(),
+        is_container: z.boolean(),
+        is_item: z.boolean(),
+        container_type: z.string().nullable(),
+        item_type: z.string().nullable(),
+        current_binding_level: z.enum(['none', 'container', 'item']),
+        has_implode_directives: z.boolean(),
+        warning: z.string().optional(),
+        recommended_fix: z.string().optional(),
+    }),
+    etag: z.string(),
+    // 6.4 — typed advisory/blocking marker. Optional so a verbatim REST
+    // passthrough that predates this field still validates, but the
+    // handler always populates it.
+    hint: z
+        .object({
+        severity: z.enum(['advisory', 'blocking']),
+        message: z.string(),
+    })
+        .optional(),
+});
+/**
+ * Classify the report into an advisory/blocking hint. A binding that
+ * sits on the container level is the structural bug Multi-Items aims to
+ * surface — that is `blocking`. Everything else is `advisory`.
+ */
+function buildHint(report) {
+    const r = (report ?? {});
+    if (r.current_binding_level === 'container') {
+        const fix = typeof r.recommended_fix === 'string' && r.recommended_fix !== ''
+            ? r.recommended_fix
+            : 'Move the binding to the first `*_item` child element.';
+        return { severity: 'blocking', message: fix };
+    }
+    return {
+        severity: 'advisory',
+        message: 'Binding looks structurally correct. Verify element_path via ' +
+            'yootheme_builder_element_list if the source still renders empty.',
+    };
+}
+/**
+ * Render a structured inspect payload into the ToolResult envelope.
+ * Shared by the cache-hit and cache-miss paths so both legs (text +
+ * structuredContent) are built identically.
+ *
+ * 6.1 — the text leg is depth-capped so a deeply-nested report cannot
+ * balloon the LLM context. structuredContent stays verbatim so it keeps
+ * validating against INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA
+ * (additionalProperties:false).
+ */
+function renderInspectResult(structured) {
+    const text = jsonResult(capInspectionDepth(structured));
+    return structuredResult(text, structured);
+}
+export async function handleInspectMultiItemsBinding({ client, cache }, { template_id, element_path }) {
+    const encoded = encodeElementPath(element_path);
+    try {
+        // 6.2 — when a cache is wired, key on the GLOBAL state etag. Every
+        // write tool bumps it, so a mutated template surfaces a fresh etag
+        // → a new key → a guaranteed miss. Read-only repeats within the TTL
+        // skip the inspect round-trip below.
+        let cacheEtag;
+        if (cache !== undefined) {
+            cacheEtag = await fetchStateEtag(client);
+            if (cacheEtag !== undefined) {
+                const cached = cache.get(template_id, element_path, cacheEtag);
+                if (cached !== undefined) {
+                    return renderInspectResult(cached);
+                }
+            }
+        }
+        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/multi-items/inspect`);
+        // 6.4 — attach the typed severity marker to the structured payload.
+        const hint = buildHint(data.report);
+        const structured = { ...data, hint };
+        if (cache !== undefined && cacheEtag !== undefined) {
+            cache.set(template_id, element_path, cacheEtag, structured);
+        }
+        return renderInspectResult(structured);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, element_path },
+            hint: 'Verify element_path via yootheme_builder_element_list. Paths are JSON-Pointer ' +
+                '(RFC-6901) style: /0/children/1. Use yootheme_builder_element_list to enumerate ' +
+                'valid paths.',
+        });
+    }
+}
+/**
+ * Read the global state ETag used as the cache-invalidation token.
+ * Returns `undefined` (cache disabled for this call) if the etag probe
+ * fails or returns a non-string — a missing etag must never poison the
+ * cache key, and a probe failure should fall through to a live inspect
+ * rather than abort the whole call.
+ */
+async function fetchStateEtag(client) {
+    try {
+        const res = await client.get('/etag');
+        return typeof res.etag === 'string' && res.etag !== '' ? res.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=inspect-handler.js.map

package/dist/tools/multi-items/inspect-handler.js.map

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