@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

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

@@ -1,37 +0,0 @@
-/**
- * `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.ZodOptional<z.ZodString>;
-    changed_paths: z.ZodOptional<z.ZodArray<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

@@ -1 +0,0 @@
-{"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;;;;;;;;;;iBAmBtC,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

@@ -1,65 +0,0 @@
-/**
- * `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()),
-    })),
-    // G2 / C0 (changed-path-on-write): the PHP success body appends the
-    // post-write etag + the JSON-Pointer / template-id path(s) it touched.
-    // handleCleanImplodeDirectives forwards the body VERBATIM via
-    // structuredResult, so these MUST be declared here — the host validates
-    // structuredContent under additionalProperties:false and a SUCCESS would
-    // otherwise trip -32602. Optional for back-compat. Mirrors
-    // PAGES_DELETE_OUTPUT_SCHEMA (pages/schemas.ts).
-    new_etag: z.string().optional(),
-    changed_paths: z.array(z.string()).optional(),
-});
-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

@@ -1 +0,0 @@
-{"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,oEAAoE;IACpE,uEAAuE;IACvE,8DAA8D;IAC9D,wEAAwE;IACxE,yEAAyE;IACzE,2DAA2D;IAC3D,iDAAiD;IACjD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAChD,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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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/inspect-handler.d.ts

@@ -1,97 +0,0 @@
-/**
- * `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";
-        }>;
-        item_child_binding_level: z.ZodOptional<z.ZodEnum<{
-            item: "item";
-            none: "none";
-        }>>;
-        is_bound: z.ZodOptional<z.ZodBoolean>;
-        has_implode_directives: z.ZodBoolean;
-        bound_source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        bound_source_exists: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-        source_missing_warning: z.ZodOptional<z.ZodString>;
-        map_location_missing: z.ZodOptional<z.ZodBoolean>;
-        field_mapping_count: z.ZodOptional<z.ZodNumber>;
-        zero_field_mappings: z.ZodOptional<z.ZodBoolean>;
-        iterator_is_leaf_renderer: z.ZodOptional<z.ZodBoolean>;
-        relation_native_binding: z.ZodOptional<z.ZodBoolean>;
-        archive_context: z.ZodOptional<z.ZodObject<{
-            query_name: z.ZodString;
-            relation: z.ZodString;
-            relation_field: z.ZodString;
-            current_term_arg: z.ZodString;
-            current_term: z.ZodNumber;
-        }, z.core.$strip>>;
-        map_location_warning: z.ZodOptional<z.ZodString>;
-        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

@@ -1 +0,0 @@
-{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyE5C,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;AAgPD,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

@@ -1,323 +0,0 @@
-/**
- * `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']),
-        // C7 (2026-06-10) — binding level of the container's first `*_item`
-        // child. Optional so a pre-C7 backend's report still validates.
-        item_child_binding_level: z.enum(['none', 'item']).optional(),
-        // C7 — single honest "is anything bound (here or on the item child)"
-        // signal. Optional for back-compat with pre-C7 reports.
-        is_bound: z.boolean().optional(),
-        has_implode_directives: z.boolean(),
-        // C7 — bound source name + live-registry existence cross-check.
-        // `bound_source_exists` is null when the registry is not wired.
-        bound_source_name: z.string().nullable().optional(),
-        bound_source_exists: z.boolean().nullable().optional(),
-        source_missing_warning: z.string().optional(),
-        // F143 — true when a bound map_item/map carries no resolved
-        // `location` leaf (the map renders 0 markers). Optional so reports
-        // for non-map elements (and pre-F143 backends) still validate.
-        map_location_missing: z.boolean().optional(),
-        // F174 — number of field mappings on the bound node (0 when unbound /
-        // mapping-less). Optional so a pre-F174 backend's report still validates.
-        field_mapping_count: z.number().int().nonnegative().optional(),
-        // F174 — true when the element IS bound but carries 0 field mappings
-        // (the N clones render only the template's static placeholder text).
-        // Optional for back-compat with pre-F174 reports.
-        zero_field_mappings: z.boolean().optional(),
-        // F189 — true when a `…List` source sits on a LEAF renderer (grid_item /
-        // any non-container) with non-empty children (the children never paint).
-        // Optional so reports for other shapes + pre-F189 backends still validate.
-        iterator_is_leaf_renderer: z.boolean().optional(),
-        // B8 (2026-06-27) — true when the binding is a relation-traversal NATIVE
-        // binding (dotted query.name + current-term `id` arg), e.g.
-        // categoryFaqs.taxonomyCategoryFaq → faq. A VALID, correctly-scoped item
-        // binding — the verdict must NOT false-flag it. Optional so reports for
-        // non-relation bindings + pre-B8 backends still validate.
-        relation_native_binding: z.boolean().optional(),
-        // B8 — the archive-context descriptor accompanying the flag (mirrors
-        // SourceRegistry::getSourceSchema()'s archive_context record). Optional
-        // (present only alongside relation_native_binding).
-        archive_context: z
-            .object({
-            query_name: z.string(),
-            relation: z.string(),
-            relation_field: z.string(),
-            current_term_arg: z.string(),
-            current_term: z.number().int(),
-        })
-            .optional(),
-        // F39 (2026-06-10) — emitted when a map/map_item is bound without a
-        // `location` field mapping (renders 0 markers). Optional so non-map
-        // reports still validate. Companion human-readable signal to the
-        // structured `map_location_missing` boolean above.
-        map_location_warning: z.string().optional(),
-        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.
- *
- * C7 (2026-06-10) — the verdict now reflects what is ACTUALLY bound, not
- * just the container-node's own binding level. Three structural bugs the
- * pre-C7 single-axis (`current_binding_level`) classifier produced:
- *
- *   1. A container bound *through* its `*_item` child reported "none" + a
- *      reassuring "structurally correct" hint. Now `is_bound` /
- *      `item_child_binding_level` make the child binding visible.
- *   2. A fully-unbound element was called "structurally correct". Now a
- *      false `is_bound` yields an honest "no source binding present" hint.
- *   3. A binding to a since-deleted source looked fine. Now
- *      `bound_source_exists === false` is `blocking` with the missing-
- *      source message.
- *
- * Precedence: container-level binding (blocking) → deleted source
- * (blocking) → nothing bound (advisory, honest) → B8 relation-traversal
- * native binding (advisory, "structurally correct (relation/current-term)")
- * → bound + live (advisory, "structurally correct").
- */
-function buildHint(report) {
-    const r = (report ?? {});
-    // F143 — a bound map with no resolved `location` leaf renders 0
-    // markers. That is a render-breaking bug, not advisory: surface it as
-    // `blocking` even though the binding level itself is "item". This is the
-    // structured-boolean entry point; the human-readable `map_location_warning`
-    // (F39, branch 1b below) is the companion signal a different backend emits.
-    if (r.map_location_missing === true) {
-        const fix = typeof r.recommended_fix === 'string' && r.recommended_fix !== ''
-            ? r.recommended_fix
-            : 'Map a single `location` field holding a combined "lat,lng" string.';
-        return {
-            severity: 'blocking',
-            message: 'Map is bound but no `location` field is mapped — no markers will ' +
-                `render. ${fix}`,
-        };
-    }
-    // F189 — a `…List` source on a LEAF renderer (grid_item / any non-container)
-    // that carries non-empty children: repeatSource clones it per row but the
-    // template renders ONLY its own slots, never its nested children → the
-    // children are render-dead and the grid shows placeholders. Render-breaking
-    // tier → blocking. The PHP inspector ships the human-readable `warning` with
-    // both recipes; surface it verbatim. Runs before the zero-mappings / generic
-    // branches so the iterator-shape bug is named first.
-    if (r.iterator_is_leaf_renderer === true) {
-        const msg = typeof r.warning === 'string' && r.warning !== ''
-            ? r.warning
-            : 'This element iterates a list source but is a LEAF renderer ' +
-                '(grid_item / *_item) — its nested children are never rendered. ' +
-                'Map fields onto the item\'s own slots (title/meta/content/image), ' +
-                'or move the List onto a container (column/fragment/row) with #parent leaves.';
-        return { severity: 'blocking', message: msg };
-    }
-    // F174 — a bound element with ZERO field mappings clones the container N
-    // times but every clone renders only the template's static placeholder
-    // text ("Title" / "Lorem ipsum"), not real data. The binding is
-    // structurally item-level so every other signal reports healthy. Same
-    // render-breaking tier as map_location_missing → blocking. The PHP
-    // inspector ships the human-readable `warning`; surface it verbatim.
-    if (r.zero_field_mappings === true) {
-        const msg = typeof r.warning === 'string' && r.warning !== ''
-            ? r.warning
-            : 'Bound to a source but with 0 field mappings — the cloned items ' +
-                'render the template\'s static placeholder text (Title / Lorem ipsum), ' +
-                'not real data. Re-bind with field_mappings AT THIS ITEM ' +
-                '(element_bind_source on this same element with non-empty ' +
-                'field_mappings). Do NOT bind the individual child leaves instead: ' +
-                'on YT5 a "#parent" leaf bind written directly under an iterating ' +
-                'item renders placeholder text.';
-        return { severity: 'blocking', message: msg };
-    }
-    // (1) Container-level binding — the original structural bug. Blocking.
-    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 };
-    }
-    // (1b) F39 — a map/map_item bound WITHOUT a `location` field mapping
-    // renders zero markers. The PHP inspector only emits map_location_warning
-    // for a genuinely-bound map pair, so its mere presence is the signal.
-    // Blocking, because the map looks healthy but shows nothing.
-    if (typeof r.map_location_warning === 'string' && r.map_location_warning !== '') {
-        return { severity: 'blocking', message: r.map_location_warning };
-    }
-    // (2) C7 bug 3 — bound source no longer exists in the live registry.
-    // `bound_source_exists` is only a hard `false` when the registry was
-    // wired AND the name was absent; `null`/`undefined` (unknown) never trips
-    // this branch.
-    if (r.bound_source_exists === false) {
-        const msg = typeof r.source_missing_warning === 'string' && r.source_missing_warning !== ''
-            ? r.source_missing_warning
-            : 'The bound source no longer exists in the live source registry — ' +
-                'the frontend will render empty. Re-bind to a current source.';
-        return { severity: 'blocking', message: msg };
-    }
-    // (3) C7 bug 2 — nothing is actually bound (neither this node nor, for a
-    // container, its item child). `is_bound` is the authoritative signal;
-    // when a pre-C7 backend omits it, fall back to current_binding_level.
-    const isBound = typeof r.is_bound === 'boolean'
-        ? r.is_bound
-        : r.current_binding_level === 'item';
-    if (!isBound) {
-        return {
-            severity: 'advisory',
-            message: 'No source binding present on this element' +
-                (r.current_binding_level !== 'item' && r.item_child_binding_level !== 'item'
-                    ? ' or its item child'
-                    : '') +
-                '. Bind a source directly: yootheme_builder_element_bind_source({ ' +
-                'template_id, element_path, source_name, field_mappings }) — for a ' +
-                'Multi-Items container, bind on the first `*_item` child.',
-        };
-    }
-    // (3b) B8 — a relation-traversal NATIVE binding (dotted query.name +
-    // current-term `id` arg, e.g. categoryFaqs.taxonomyCategoryFaq → faq). It is
-    // a VALID, correctly-scoped item-level binding. The pre-B8 verdict had no
-    // signal for it and fell through to the generic "structurally correct"
-    // message; worse, an over-eager existence check could mis-read the dotted
-    // name. Surface an EXPLICIT advisory naming the relation + current-term so
-    // the agent stops treating a working archive binding as broken/none. Runs
-    // AFTER every blocking branch (deleted source / container-level / map /
-    // zero-mappings / iterator-leaf) and after the unbound check — so a genuinely
-    // broken relation binding still reports blocking, never this advisory.
-    if (r.relation_native_binding === true) {
-        const ac = r.archive_context !== null && typeof r.archive_context === 'object'
-            ? r.archive_context
-            : {};
-        const relation = typeof ac.relation === 'string' && ac.relation !== '' ? ac.relation : 'relation';
-        const relationField = typeof ac.relation_field === 'string' && ac.relation_field !== '' ? ac.relation_field : 'the relation field';
-        const termArg = typeof ac.current_term_arg === 'string' && ac.current_term_arg !== '' ? ac.current_term_arg : 'id';
-        return {
-            severity: 'advisory',
-            message: 'Binding looks structurally correct (relation/current-term). This is a ' +
-                `native relation-traversal binding — it follows the "${relation}" relation ` +
-                `to "${relationField}" scoped to the CURRENT term (${termArg}: 0), the canonical ` +
-                'archive-context shape. It renders the current term\'s related items on an ' +
-                'archive/term page and is correctly scoped — NOT broken. Verify on a real ' +
-                'archive/term URL if it still renders empty.',
-        };
-    }
-    // (4) C7 bug 1 — bound through the item child. Surface that explicitly so
-    // the agent does not mistake the container's own "none" level for "unbound".
-    if (r.item_child_binding_level === 'item') {
-        return {
-            severity: 'advisory',
-            message: 'Binding looks structurally correct — the source is bound at the ' +
-                'item level (on the `*_item` child), which is the canonical ' +
-                'Multi-Items shape. Verify element_path via ' +
-                'yootheme_builder_element_list if the source still renders empty.',
-        };
-    }
-    // (5) Genuinely item-bound with a live (or unknown) source.
-    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