@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/tools/sublayout/inspect-sublayout-handler.js

@@ -1,181 +0,0 @@
-/**
- * `inspect_sublayout` handler — surfaces the YT5 `< SUBLAYOUT` mechanism
- * (F154 / F93) via REST round-trip.
- *
- * YT5's `< SUBLAYOUT` breadcrumb conflates TWO structurally different things:
- *
- *  1. The `fragment` element — a real container node whose bind-able leaves
- *     (title, meta, crest image) live in `fragment.children[...]`, NOT on the
- *     `panel`/`grid_item` the Customizer first selected.
- *  2. The render-time inner grid — `panel`/`grid_item` build a `uk-grid` from
- *     PROPS injected by the container at render. There is NO JSON node for it,
- *     and it is GATED: the inner wrapper is only emitted when
- *     `title_align === 'left'` / `image_align ∈ {left,right}`. Patching
- *     `title_grid_width` without first satisfying the gate is a SILENT no-op.
- *
- * Companion of the PHP `SublayoutInspector` — see
- * src/modules/builder-source-binding/src/SublayoutInspector.php for the
- * report shape. Mirrors the `inspect_multi_items_binding` handler:
- * optional InspectionCache keyed on (template_id, element_path, global-etag).
- *
- * @license MIT
- */
-import { z } from 'zod';
-import { encodeElementPath, encodeTemplateId } from '../../client.js';
-import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
-import { capInspectionDepth } from '../multi-items/format/inspection-format.js';
-/** A single render-time inner-grid axis (title | image). */
-const GRID_AXIS_SCHEMA = z.object({
-    gate_prop: z.string(),
-    gate_value: z.string().nullable(),
-    gate_satisfied: z.boolean(),
-    active_props: z.record(z.string(), z.unknown()),
-});
-/** A bindable leaf inside a fragment subtree. */
-const BINDABLE_LEAF_SCHEMA = z.object({
-    leaf_path: z.string(),
-    element_type: z.string(),
-    bindable_props: z.array(z.string()),
-    is_bound: z.boolean(),
-    bound_source_name: z.string().nullable(),
-    // null when the registry is not wired (UNKNOWN, never a false miss).
-    bound_source_exists: z.boolean().nullable().optional(),
-});
-/** A direct fragment child of the addressed container. */
-const FRAGMENT_SCHEMA = z.object({
-    fragment_path: z.string(),
-    child_count: z.number().int().nonnegative(),
-    bindable_leaves: z.array(BINDABLE_LEAF_SCHEMA),
-});
-/** A single enrichment-hazard warning. */
-const SUBLAYOUT_WARNING_SCHEMA = z.object({
-    code: z.string(),
-    message: z.string(),
-    props: z.array(z.string()).optional(),
-    gate_prop: z.string().optional(),
-});
-export const INSPECT_SUBLAYOUT_OUTPUT_SCHEMA = z.object({
-    template_id: z.string(),
-    report: z.object({
-        element_path: z.string(),
-        element_type: z.string(),
-        is_sublayout_capable: z.boolean(),
-        fragments: z.array(FRAGMENT_SCHEMA),
-        grid: z.object({
-            title: GRID_AXIS_SCHEMA,
-            image: GRID_AXIS_SCHEMA,
-        }),
-        warnings: z.array(SUBLAYOUT_WARNING_SCHEMA),
-        no_sublayout: z.boolean(),
-    }),
-    etag: z.string(),
-    // Typed advisory/blocking marker. `blocking` when an ungated grid prop is
-    // a silent no-op (the trap this tool exists for); `advisory` otherwise.
-    hint: z
-        .object({
-        severity: z.enum(['advisory', 'blocking']),
-        message: z.string(),
-    })
-        .optional(),
-});
-/**
- * Classify the report into an advisory/blocking hint.
- *
- * Precedence: an `ungated_grid_prop` warning (a silent no-op — the trap this
- * tool exists for) is `blocking`; everything else is `advisory`. A
- * sublayout-less element gets a short "nothing to enrich" advisory so the
- * agent does not keep probing.
- */
-function buildHint(report) {
-    const r = (report ?? {});
-    const warnings = Array.isArray(r.warnings)
-        ? r.warnings
-        : [];
-    const ungated = warnings.find((w) => w.code === 'ungated_grid_prop');
-    if (ungated !== undefined && typeof ungated.message === 'string' && ungated.message !== '') {
-        return { severity: 'blocking', message: ungated.message };
-    }
-    if (r.no_sublayout === true) {
-        return {
-            severity: 'advisory',
-            message: 'This element has no `fragment` sublayout child and no inner-grid ' +
-                'props — there is nothing to enrich here. Bind a source directly on a ' +
-                'leaf via yootheme_builder_element_bind_source, or add a fragment first.',
-        };
-    }
-    if (r.is_sublayout_capable === false) {
-        return {
-            severity: 'advisory',
-            message: 'This element type is not sublayout-capable (panel / grid_item). The ' +
-                'fragment subtree + inner-grid gate apply only to those containers.',
-        };
-    }
-    return {
-        severity: 'advisory',
-        message: 'Sublayout looks consistent. Bind the source on a `fragment.children` leaf ' +
-            '(use a leaf_path from the report), NOT on this container. Inner-grid props ' +
-            'only take effect when their gate (title_align=left / image_align=left|right) ' +
-            'is satisfied.',
-    };
-}
-/**
- * Render a structured inspect payload into the ToolResult envelope. 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_SUBLAYOUT_OUTPUT_SCHEMA (additionalProperties:false).
- */
-function renderInspectResult(structured) {
-    const text = jsonResult(capInspectionDepth(structured));
-    return structuredResult(text, structured);
-}
-export async function handleInspectSublayout({ client, cache }, { template_id, element_path }) {
-    const encoded = encodeElementPath(element_path);
-    try {
-        // When a cache is wired, key on the GLOBAL state etag. Every write
-        // 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}/sublayout/inspect`);
-        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: 'Pass the CONTAINER element_path (a `panel` or `grid_item`) — the tool ' +
-                'descends into its fragment child itself. Verify the path via ' +
-                'yootheme_builder_element_list (JSON-Pointer, RFC-6901: /0/children/1).',
-        });
-    }
-}
-/**
- * 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.
- */
-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-sublayout-handler.js.map

package/dist/tools/sublayout/inspect-sublayout-handler.js.map

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