@wootsup/yt-builder-mcp 1.11.0 → 2.0.0

package/dist/tools/sources/handlers-bind.js

@@ -1,655 +0,0 @@
-/**
- * Source-binding write handlers (`element_bind_source`,
- * `element_unbind_source`).
- *
- * Split out of `./handlers.ts` to keep each file under the 200-LoC
- * budget. Wave G.4.2 adds destructive-confirm elicitation;
- * Wave G.4.3 adds ambiguity-resolution elicitation.
- *
- * @license MIT
- */
-import { elicitChoice, elicitConfirmation } from '@getimo/mcp-toolkit';
-import { z } from 'zod';
-import { encodeElementPath, encodeTemplateId } from '../../client.js';
-import { RestError } from '../../errors.js';
-import { flattenSourcesPayload, mapSourceRow, } from '../format/sources-format.js';
-import { ambiguityFallbackError, } from '../elicitation.js';
-import { confirmGuard, errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
-import { detailResult } from '@getimo/mcp-toolkit';
-import { GRID_ITEM_ITERATOR_REJECT, SLOT_COLLISION_STEERING, } from '../bind-guidance.js';
-/**
- * Wave-12 F9 — extract validation-hint fields surfaced by the WP REST
- * plugin when `source_name` is rejected (`unknown_source` code). The PHP
- * controller writes `given`, `did_you_mean`, and `all_published_sources`
- * into the WP_Error data; WordPress serialises that under the response
- * body's `data` key. Surface those hints into the tool-result `context`
- * so the agent can correct + retry in one step.
- */
-function extractUnknownSourceHints(body) {
-    if (body === null || typeof body !== 'object')
-        return null;
-    const root = body;
-    if (root.code !== 'yootheme_builder_mcp.source_binding.unknown_source')
-        return null;
-    const data = root.data;
-    if (data === null || typeof data !== 'object')
-        return null;
-    const d = data;
-    return {
-        given: typeof d.given === 'string' ? d.given : undefined,
-        did_you_mean: d.did_you_mean,
-        all_published_sources: d.all_published_sources,
-    };
-}
-/**
- * F189 — true iff the REST error body is the slot-collision reject (409). The
- * WP plugin writes `code` = `…source_binding.slot_collision`; both platforms
- * also carry `data.error_code === 'slot_collision'` (WordPress nests hint data
- * under `data`; the Joomla envelope surfaces the same `error_code`).
- */
-function isSlotCollision(body) {
-    if (body === null || typeof body !== 'object')
-        return false;
-    const root = body;
-    if (typeof root.code === 'string' &&
-        root.code.endsWith('source_binding.slot_collision')) {
-        return true;
-    }
-    if (root.error_code === 'slot_collision')
-        return true;
-    const data = root.data;
-    if (data !== null && typeof data === 'object') {
-        return data.error_code === 'slot_collision';
-    }
-    return false;
-}
-/** Pull a `list<string>` from a passthrough body field, or `[]`. */
-function stringList(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((k) => typeof k === 'string');
-}
-/**
- * F174 — the bind succeeded but with ZERO field mappings: each of the N
- * cloned items will render only the template's static placeholder text
- * ("Title" / "Lorem ipsum"), not real data. This is a silent footgun: a
- * caged agent bound source_name + bindingLevel only, the call returned 200
- * + binding_level:"item", and element_get_binding reported a healthy-looking
- * binding — but the frontend showed N identical placeholder cards. The
- * warning is NOT a hard reject (a first bind of just the source can be a
- * legitimate intermediate step), but it must be unmissable.
- *
- * `hadMappings` is true when the bind REQUEST carried a non-empty
- * field_mappings object. We fire only when the request had no mappings AND
- * the response did not report any dropped mappings (a re-bind that shrinks an
- * existing map keeps real data on the kept props — that is the F147 warning's
- * territory, not this one).
- */
-function zeroFieldMappingsWarning() {
-    return ('0 field mappings bound — the cloned items will render the template\'s ' +
-        'static placeholder texts (Title / Lorem ipsum), not real data. ' +
-        'Re-bind with field_mappings AT THIS ITEM (call element_bind_source ' +
-        'again on THIS same element_path with a non-empty ' +
-        'field_mappings:{<element_prop>:<source_field>}). Do NOT bind the ' +
-        'individual child leaves instead: on YT5 a "#parent" leaf bind written ' +
-        'directly under an iterating item renders placeholder text — the ' +
-        'field_mappings-at-the-item form is the shape that resolves. Discover ' +
-        'props via yootheme_builder_element_type_get_schema, source fields via ' +
-        'apimapper_yootheme_binding_for_flow.');
-}
-/**
- * F129 + F147 + F174 — when the REST plugin's bind response carries
- * `unknown_prop_keys` (field_mappings keys the target element-type does
- * not render) and/or `dropped_field_mappings` (leaves the new, smaller
- * field_mappings dropped from the prior binding — full replace, not
- * merge), promote them to a TOP-LEVEL `warning` string so both silent-
- * footgun signals are the first thing the agent sees. F174: when the bind
- * persisted a source binding with ZERO field mappings (request had none and
- * none were dropped), promote the placeholder-render footgun warning too.
- * Returns the body unchanged when no signal is present (no warning on the
- * happy path).
- */
-function withBindWarnings(body, hadMappings) {
-    if (body === null || typeof body !== 'object' || Array.isArray(body))
-        return body;
-    const root = body;
-    const unknownKeys = stringList(root.unknown_prop_keys);
-    const droppedKeys = stringList(root.dropped_field_mappings);
-    // SOURCES_BINDING-9: the PHP chokepoint may already have set a top-level
-    // `warning` (e.g. the SourceTransform::repeatSource container-clone warning:
-    // "Binding lives on the container. YT-Pro clones the container N times…").
-    // SEED `parts` with it so it is PRESERVED — the field-mappings parts below
-    // append AFTER it. The former `parts.join(' ')` overwrote `root.warning`
-    // outright, silently discarding that container-clone footgun signal.
-    const parts = [];
-    if (typeof root.warning === 'string' && root.warning.trim() !== '') {
-        parts.push(root.warning);
-    }
-    if (unknownKeys.length > 0) {
-        parts.push(`These field_mappings keys are not props the target element renders, ` +
-            `so their values will be silently dropped: ${unknownKeys.join(', ')}. ` +
-            `Run yootheme_builder_element_type_get_schema for valid prop names ` +
-            `(see unknown_prop_keys_did_you_mean for suggestions), or re-bind onto ` +
-            `an element that exposes these props.`);
-    }
-    // G2 (WF1 Phase-2) — the VALUE-side mirror of unknown_prop_keys. A
-    // field_mappings VALUE that names a source-field the bound flow does NOT
-    // emit binds to nothing → the bind returns 200 but the element renders
-    // blank. The PHP chokepoint is the only place that resolves BOTH the
-    // source's field set AND the target element, so it flags these as
-    // `unknown_source_field_values` (with the available set in
-    // `unknown_source_field_values_available`). Promote both into the
-    // top-level warning so the agent sees which field is wrong AND the
-    // valid choices, in one step.
-    const unknownFieldValues = stringList(root.unknown_source_field_values);
-    if (unknownFieldValues.length > 0) {
-        const available = stringList(root.unknown_source_field_values_available);
-        const availableHint = available.length > 0
-            ? ` Available source fields: ${available.join(', ')}.`
-            : '';
-        parts.push(`These field_mappings values name source fields the bound source does ` +
-            `not emit, so they bind to nothing (the element renders blank): ` +
-            `${unknownFieldValues.join(', ')}.${availableHint} Re-bind with a ` +
-            `source-field name the flow actually emits — list them via ` +
-            `apimapper_yootheme_binding_for_flow.`);
-    }
-    if (droppedKeys.length > 0) {
-        parts.push(`field_mappings is a full REPLACE, not a merge — this re-bind dropped ` +
-            `the previously-bound prop(s): ${droppedKeys.join(', ')}. If that was ` +
-            `unintended, re-bind with the full set (include the dropped keys).`);
-    }
-    // F174 — only when the request bound a source with no mappings AND no
-    // prior mappings were dropped. A bind that dropped keys still kept real
-    // data on the survivors → not a zero-mappings placeholder situation.
-    if (!hadMappings && droppedKeys.length === 0 && bindPersistedSource(root)) {
-        parts.push(zeroFieldMappingsWarning());
-    }
-    // F189 — the bind landed a `…List` source on a LEAF renderer (grid_item /
-    // any non-container) that ALSO carries nested children. The item's own slot
-    // bind resolved, but its nested children are render-dead (the template never
-    // renders them). Promote the reject-recipe text so the agent fixes the shape
-    // instead of shipping a placeholder grid.
-    if (root.iterator_is_leaf_renderer === true) {
-        parts.push(GRID_ITEM_ITERATOR_REJECT);
-    }
-    if (parts.length === 0)
-        return body;
-    return { ...root, warning: parts.join(' ') };
-}
-/**
- * F174 — did the bind response persist an actual source binding (vs an
- * unbind / no-op)? True when the response `binding.source_name` (or the
- * top-level `source_name`) is a non-empty string. Guards the zero-mappings
- * warning so it never fires on an unbind echo.
- */
-function bindPersistedSource(root) {
-    const fromBinding = root.binding !== null && typeof root.binding === 'object' && !Array.isArray(root.binding)
-        ? root.binding.source_name
-        : undefined;
-    const name = typeof fromBinding === 'string' ? fromBinding : root.source_name;
-    return typeof name === 'string' && name.length > 0;
-}
-// ─── element_bind_source (G.4.3 — ambiguity resolution) ─────────────
-/**
- * Look up sources matching `source_name`. Returns at most one row per
- * (name + origin) tuple; cross-plugin name collisions yield multiple
- * candidates that need disambiguation.
- *
- * TODO(v0.3): cache /sources per session to avoid the round-trip on
- * every bind. The current "fetch on every bind" call is the only REST
- * round-trip introduced by ambiguity resolution and dominates bind
- * latency — see tests/perf/bind-latency.test.ts for the pin.
- */
-async function fetchSourceCandidates(client, source_name) {
-    const data = await client.get('/sources');
-    const payload = data.sources ?? data;
-    const flat = flattenSourcesPayload(payload);
-    return flat.map(mapSourceRow).filter((r) => r.name === source_name);
-}
-/**
- * A single `field_mappings` value. F96/F82 (2026-06-10): EITHER a plain
- * source-field name string, OR a structured `{name, filters?}` object that
- * carries an explicit YT5 filters operator (e.g. `{condition: '!!'}` on a
- * `_condition` prop, or `{date: 'D, d.m.y'}` for a date format). Mirrors the
- * `field_mappings` union in `./builders.ts`. The handler forwards the value
- * verbatim — the PHP SourcesController normalises + persists it.
- */
-/**
- * SOURCES_BINDING-8 — narrow the PHP `unknown_prop_keys_did_you_mean` body field
- * (a map of unknown-key → closest known prop names) to the typed shape the
- * strict output schema declares, dropping a malformed payload rather than
- * letting it trip the -32602 gate.
- */
-function isDidYouMeanMap(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    return Object.values(value).every((v) => Array.isArray(v) && v.every((s) => typeof s === 'string'));
-}
-export async function handleElementBindSource({ client, elicitation }, input) {
-    const { template_id, element_path, source_name, source_id, etag, bindingLevel, field_mappings, relation, field, arguments: fieldArguments, directives, query_arguments, } = input;
-    const encoded = encodeElementPath(element_path);
-    // Wave G.4.3 — ambiguity resolution.
-    //
-    // If `source_id` is supplied, the caller has already disambiguated;
-    // skip the /sources lookup entirely.
-    //
-    // Otherwise look up rows matching `source_name`:
-    //   - 0 matches: fall through to the bind call; the REST plugin
-    //     returns its own structured 404 with a precise hint (sources
-    //     can be added between the lookup and the call).
-    //   - 1 match: unique → bind directly.
-    //   - ≥2 matches: cross-plugin collision (e.g. an apimapper flow
-    //     AND a wordpress source both named "Posts"). Elicit a choice
-    //     on supporting hosts; on unsupported hosts, return a
-    //     structured `ambiguityFallbackError` listing every candidate
-    //     so the agent can retry with `source_id`.
-    let resolvedBody = { source_name };
-    if (bindingLevel !== undefined) {
-        resolvedBody.bindingLevel = bindingLevel;
-    }
-    if (field_mappings !== undefined) {
-        resolvedBody.field_mappings = field_mappings;
-    }
-    // B5 — forward the relation/field selector verbatim. `arguments` +
-    // `directives` are only meaningful alongside `field`, but we forward them
-    // whenever present and let the PHP SourcesController be the single
-    // place that decides how they land in `query.field` (one engine, both
-    // platforms). Omitting all four preserves the legacy flat-source bind.
-    if (relation !== undefined) {
-        resolvedBody.relation = relation;
-    }
-    if (field !== undefined) {
-        resolvedBody.field = field;
-    }
-    if (fieldArguments !== undefined) {
-        resolvedBody.arguments = fieldArguments;
-    }
-    if (directives !== undefined) {
-        resolvedBody.directives = directives;
-    }
-    // N2 — forward the TOP-LEVEL query arguments verbatim. The PHP
-    // SourcesController is the single place that lands them in
-    // `source.query.arguments` (one engine, both platforms).
-    if (query_arguments !== undefined) {
-        resolvedBody.query_arguments = query_arguments;
-    }
-    if (source_id === undefined) {
-        const candidates = await fetchSourceCandidates(client, source_name);
-        if (candidates.length > 1) {
-            const elicitCandidates = candidates.map((c) => ({
-                id: `${c.origin}:${c.name}`,
-                label: `${c.label || c.name} (${c.origin}${c.kind ? `/${c.kind}` : ''})`,
-            }));
-            const picked = elicitation
-                ? await elicitChoice(elicitation, `Multiple sources named "${source_name}" exist. Pick which ` +
-                    `one to bind to "${element_path}".`, elicitCandidates.map((c) => c.id))
-                : null;
-            if (picked === null) {
-                return ambiguityFallbackError({
-                    code: 'source_ambiguous',
-                    paramName: 'source_id',
-                    what: 'sources',
-                    candidates: elicitCandidates,
-                    context: { template_id, element_path, source_name },
-                });
-            }
-            resolvedBody = { ...resolvedBody, source_id: picked };
-        }
-    }
-    else {
-        resolvedBody = { ...resolvedBody, source_id };
-    }
-    try {
-        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/binding`, { body: resolvedBody, etag });
-        // F129 + F147 + F174 — the bind persisted (200), but the REST plugin
-        // may have flagged field_mappings keys the target element-type does
-        // not render (`unknown_prop_keys`) and/or leaves the new, smaller
-        // map dropped from the prior binding (`dropped_field_mappings` —
-        // full replace, not merge); and the bind may have persisted a source
-        // with ZERO field mappings (renders only template placeholders).
-        // All are silent footguns at render time. Lift them into a TOP-LEVEL
-        // warning so the agent notices and corrects, rather than leaving the
-        // signal buried in the passthrough body.
-        const hadMappings = field_mappings !== undefined && Object.keys(field_mappings).length > 0;
-        return jsonResult(withBindWarnings(data, hadMappings));
-    }
-    catch (e) {
-        // Wave-12 F9 — surface unknown-source hints directly into the
-        // result context so the agent can correct the source_name and
-        // retry in one step instead of guessing.
-        const baseContext = {
-            template_id,
-            element_path,
-            source_name,
-            ...(source_id ? { source_id } : {}),
-        };
-        if (e instanceof RestError) {
-            // F189 — slot collision (409): two fields would land on the same
-            // parent prop slot during F188 consolidation, OR the lifted key is
-            // not a slot of the parent type. The server's message already names
-            // the slot + recipe; surface the canonical steering as the hint so
-            // the agent gives each field its own leaf / a distinct slot.
-            if (isSlotCollision(e.body)) {
-                return errorResult({
-                    error: e,
-                    context: baseContext,
-                    hint: SLOT_COLLISION_STEERING,
-                });
-            }
-            const hints = extractUnknownSourceHints(e.body);
-            if (hints !== null) {
-                if (hints.did_you_mean !== undefined) {
-                    baseContext.did_you_mean = hints.did_you_mean;
-                }
-                if (hints.all_published_sources !== undefined) {
-                    baseContext.all_published_sources = hints.all_published_sources;
-                }
-                return errorResult({
-                    error: e,
-                    context: baseContext,
-                    hint: 'source_name does not match any published source. Pick from ' +
-                        '`all_published_sources` (full list) or `did_you_mean` (closest matches) ' +
-                        'in the context, or run yootheme_builder_sources_list to refresh.',
-                });
-            }
-        }
-        return errorResult({
-            error: e,
-            context: baseContext,
-            hint: 'Verify source_name via yootheme_builder_sources_list. On 412 ' +
-                'refresh ETag and retry.',
-        });
-    }
-}
-// ─── element_unbind_source (destructive — G.4.2) ────────────────────
-export async function handleElementUnbindSource({ client, elicitation }, input) {
-    const { template_id, element_path, etag, confirm } = input;
-    if (confirm !== true) {
-        if (confirm === false || !elicitation) {
-            return confirmGuard({
-                operation: 'unbind source',
-                details: { template_id, element_path },
-            });
-        }
-        const accepted = await elicitConfirmation(elicitation, `Unbind the dynamic source from element "${element_path}" in template ` +
-            `"${template_id}"? This may break dynamic-content rendering.`);
-        if (!accepted) {
-            return confirmGuard({
-                operation: 'unbind source',
-                details: { template_id, element_path },
-            });
-        }
-    }
-    const encoded = encodeElementPath(element_path);
-    try {
-        const data = await client.delete(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/binding`, { etag });
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: 'On 412 refresh via yootheme_builder_get_etag and retry.',
-        });
-    }
-}
-// ─── element_set_source (F2 — surgical source-edit) ─────────────────
-/**
- * F2 (Glöckle HANDOFF-4) — the `element_set_source` STRICT output schema.
- *
- * A default (strip) ZodObject so a strict (`additionalProperties:false`) host
- * accepts the structuredContent and the shape-pin guard's `.strict()` re-parse
- * passes. The success body the PHP `SourcesController::set_source` returns is
- * `{template_id, element_path, etag, new_etag, changed_paths}` — EVERY key here
- * must be DECLARED, else a strict MCP host -32602-rejects the success (the G2
- * `changed_paths` lesson).
- */
-export const ELEMENT_SET_SOURCE_OUTPUT_SCHEMA = z.object({
-    template_id: z.string(),
-    element_path: z.string(),
-    // PG2 (addressing-coherence): the canonical rel_path form (`/children/0/…`,
-    // element_list's shape) alongside the fully-qualified element_path /
-    // changed_paths, ADDITIVE. DECLARED here because the handler PROJECTS the
-    // structured object (strips undeclared keys) — an omitted declaration would
-    // silently drop the field. `.optional()` keeps back-compat with pre-PG2
-    // plugins whose body omits them.
-    rel_path: z.string().optional(),
-    // SOURCES_BINDING-16: `etag` is the POST-WRITE ETag (== new_etag), so
-    // response.etag is ALWAYS safe to chain into the next write. It used to echo
-    // the INPUT (pre-write) If-Match, which chained to a stale value and 412'd
-    // the follow-up write — inconsistent with scaffold_section/element_add,
-    // which surface the post-write etag. Kept alongside `new_etag` (identical)
-    // for back-compat with callers reading either name.
-    etag: z.string(),
-    // The bumped ETag after the surgical write — pass as `etag` on the next write.
-    new_etag: z.string(),
-    // The JSON-pointer(s) the write touched (just the edited node — blast-radius 0).
-    changed_paths: z.array(z.string()),
-    // PG2: the rel_path pendant of changed_paths (same `/children/0/…` shape).
-    changed_rel_paths: z.array(z.string()).optional(),
-    // SOURCES_BINDING-8: element-prop keys (from source.props / source_extended.props)
-    // the target element-type does NOT render — a NON-FATAL warning mirroring the
-    // bind-path F129 check. Present only when non-empty (a strict host would else
-    // reject an undeclared key). DECLARED optional so a clean write / a Joomla
-    // host (which lacks the check) stays byte-identical.
-    unknown_prop_keys: z.array(z.string()).optional(),
-    unknown_prop_keys_hint: z.string().optional(),
-    unknown_prop_keys_did_you_mean: z.record(z.string(), z.array(z.string())).optional(),
-});
-/**
- * F2 — surgically set a PRECOMPOSED `source` (+ optional `source_extended`) onto
- * ONE element at a pointer, ETag-locked, leaving the rest of the layout
- * byte-unchanged. The two carriers are author-composed objects forwarded
- * VERBATIM to `PUT /pages/<id>/elements/<path>/source`; the PHP controller is the
- * single place that persists them onto `node.source` / `node.source_extended`.
- */
-export async function handleElementSetSource({ client }, input) {
-    const { template_id, element_path, etag, source, source_extended } = input;
-    const encoded = encodeElementPath(element_path);
-    // Forward only the keys the caller supplied. `source_extended` is forwarded
-    // even when explicitly null (that CLEARS the carrier server-side); it is
-    // omitted only when undefined.
-    const body = {};
-    if (source !== undefined)
-        body.source = source;
-    if (source_extended !== undefined)
-        body.source_extended = source_extended;
-    try {
-        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/source`, { body, etag });
-        // The PHP success body carries exactly the strict output-schema keys;
-        // project them so structuredContent never carries an undeclared key (a
-        // strict host -32602-rejects extras). Fall back to the request values
-        // for template_id/element_path so the shape is always complete.
-        const changedPaths = Array.isArray(data.changed_paths)
-            ? data.changed_paths.filter((p) => typeof p === 'string')
-            : [typeof data.element_path === 'string' ? data.element_path : element_path];
-        // PG2 (addressing-coherence): forward the canonical rel_path pendants the
-        // PHP body now carries. Present only on PG2+ plugins — the projection
-        // omits them when absent so pre-PG2 hosts stay byte-identical.
-        const relPath = typeof data.rel_path === 'string' ? data.rel_path : undefined;
-        const changedRelPaths = Array.isArray(data.changed_rel_paths)
-            ? data.changed_rel_paths.filter((p) => typeof p === 'string')
-            : undefined;
-        // SOURCES_BINDING-16: prefer the POST-WRITE etag for the chainable `etag`
-        // field (falls back to the request/data etag only when no new_etag came back).
-        const newEtag = typeof data.new_etag === 'string' ? data.new_etag : '';
-        const postWriteEtag = newEtag !== '' ? newEtag : (typeof data.etag === 'string' ? data.etag : etag);
-        // SOURCES_BINDING-8: forward the bind-parity unknown-prop-key warning the
-        // PHP set_source chokepoint now echoes (element-prop keys the target type
-        // does not render). Present only on a WP host that found unknowns; a clean
-        // write / a Joomla host omits them (the projection drops the absent keys).
-        const unknownPropKeys = Array.isArray(data.unknown_prop_keys)
-            ? data.unknown_prop_keys.filter((k) => typeof k === 'string')
-            : undefined;
-        const unknownPropKeysHint = typeof data.unknown_prop_keys_hint === 'string' ? data.unknown_prop_keys_hint : undefined;
-        const unknownPropKeysDidYouMean = isDidYouMeanMap(data.unknown_prop_keys_did_you_mean)
-            ? data.unknown_prop_keys_did_you_mean
-            : undefined;
-        const hasUnknownProps = unknownPropKeys !== undefined && unknownPropKeys.length > 0;
-        const structured = {
-            template_id: typeof data.template_id === 'string' ? data.template_id : template_id,
-            element_path: typeof data.element_path === 'string' ? data.element_path : element_path,
-            ...(relPath !== undefined ? { rel_path: relPath } : {}),
-            etag: postWriteEtag,
-            new_etag: newEtag,
-            changed_paths: changedPaths,
-            ...(changedRelPaths !== undefined ? { changed_rel_paths: changedRelPaths } : {}),
-            ...(hasUnknownProps ? { unknown_prop_keys: unknownPropKeys } : {}),
-            ...(hasUnknownProps && unknownPropKeysHint !== undefined
-                ? { unknown_prop_keys_hint: unknownPropKeysHint }
-                : {}),
-            ...(hasUnknownProps && unknownPropKeysDidYouMean !== undefined
-                ? { unknown_prop_keys_did_you_mean: unknownPropKeysDidYouMean }
-                : {}),
-        };
-        const toolkitResult = detailResult({
-            title: 'Source set (surgical)',
-            groups: [
-                {
-                    label: 'Surgical source-edit',
-                    entries: [
-                        { key: 'template_id', label: 'Template', value: structured.template_id, format: 'text' },
-                        { key: 'element_path', label: 'Element', value: structured.element_path, format: 'code', copyable: true },
-                        { key: 'new_etag', label: 'New ETag', value: structured.new_etag, format: 'badge', copyable: true },
-                        { key: 'changed_paths', label: 'Changed paths', value: structured.changed_paths.join(', '), format: 'code' },
-                    ],
-                },
-                // SOURCES_BINDING-8: surface the unknown-prop-key warning in the
-                // TEXT leg too, so an agent reading only the detail sees the dead
-                // mapping (not just the structured leg).
-                ...(hasUnknownProps
-                    ? [{
-                            label: 'Warning — unknown prop keys',
-                            entries: [
-                                { key: 'unknown_prop_keys', label: 'Dropped keys', value: (unknownPropKeys ?? []).join(', '), format: 'code' },
-                                ...(unknownPropKeysHint !== undefined
-                                    ? [{ key: 'hint', label: 'Hint', value: unknownPropKeysHint }]
-                                    : []),
-                            ],
-                        }]
-                    : []),
-            ],
-        });
-        return structuredResult(toolkitResult, structured);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: 'On 412 refresh the ETag via yootheme_builder_get_etag and retry. ' +
-                'On 400 invalid_body, ensure `source.query.name` is a non-empty string ' +
-                '(e.g. "categoryFaqs.taxonomyCategoryFaq"). Verify element_path via ' +
-                'yootheme_builder_element_list.',
-        });
-    }
-}
-// ─── rename_source (N1 — template-wide source/field rename) ─────────
-/**
- * N1 (Glöckle HANDOFF-5) — the `rename_source` STRICT output schema.
- *
- * A default (strip) ZodObject so a strict (`additionalProperties:false`) host
- * accepts the structuredContent and the shape-pin guard's `.strict()` re-parse
- * passes. The success body the PHP `SourcesController::rename_source` returns is
- * `{template_id, replaced_count, changed_paths, etag, new_etag}` — EVERY key here
- * must be DECLARED, else a strict MCP host -32602-rejects the success (the G2
- * `changed_paths` lesson).
- */
-export const RENAME_SOURCE_OUTPUT_SCHEMA = z.object({
-    template_id: z.string(),
-    // The number of BOUND nodes whose binding was rewritten template-wide.
-    replaced_count: z.number(),
-    // The rel-path pointer of each changed node, in document order.
-    changed_paths: z.array(z.string()),
-    // SOURCES_BINDING-16: the POST-WRITE ETag (== new_etag) — always safe to
-    // chain into the next write (was the pre-write input etag, which 412'd).
-    // On a dry_run nothing persists, so etag == new_etag == the current ETag.
-    etag: z.string(),
-    // The bumped ETag after the write — pass as `etag` on the next write.
-    new_etag: z.string(),
-    // SOURCES_BINDING-15: present + true ONLY on a dry_run preflight (the
-    // template-wide rename was computed + previewed but NOT persisted).
-    dry_run: z.boolean().optional(),
-    // SOURCES_BINDING-15: whether the (dry-run) rename would actually rewrite
-    // any binding (`replaced_count > 0`).
-    would_change: z.boolean().optional(),
-});
-/**
- * N1 — TEMPLATE-WIDE rename every matching binding's source-name + field-name
- * tokens in ONE ETag-locked write. The rename spec (the single-source shorthand
- * `from`/`to` and/or the explicit `source_map`/`field_map`) is forwarded VERBATIM
- * to `PUT /pages/<id>/rename-source`; the PHP controller is the single place that
- * runs the SourceRenamer engine across the whole template, preserving every
- * binding's arguments / props / field_mappings and leaving non-matching bindings
- * byte-identical.
- */
-export async function handleRenameSource({ client }, input) {
-    const { template_id, etag, from, to, source_map, field_map, dry_run } = input;
-    // Forward only the keys the caller supplied — the PHP controller folds the
-    // `from`/`to` shorthand into source_map and validates "at least one rename
-    // instruction" on its end (one engine, both platforms).
-    const body = {};
-    if (from !== undefined)
-        body.from = from;
-    if (to !== undefined)
-        body.to = to;
-    if (source_map !== undefined)
-        body.source_map = source_map;
-    if (field_map !== undefined)
-        body.field_map = field_map;
-    // SOURCES_BINDING-15: forward `dry_run` only when set so an ordinary rename
-    // stays byte-identical; the PHP branch previews without persisting.
-    if (dry_run)
-        body.dry_run = true;
-    try {
-        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/rename-source`, { body, etag });
-        // The PHP success body carries exactly the strict output-schema keys;
-        // project them so structuredContent never carries an undeclared key (a
-        // strict host -32602-rejects extras). Fall back to request/sane values so
-        // the shape is always complete.
-        const changedPaths = Array.isArray(data.changed_paths)
-            ? data.changed_paths.filter((p) => typeof p === 'string')
-            : [];
-        // SOURCES_BINDING-16: `etag` = the POST-WRITE etag (chainable), not the input.
-        const newEtag = typeof data.new_etag === 'string' ? data.new_etag : '';
-        const postWriteEtag = newEtag !== '' ? newEtag : (typeof data.etag === 'string' ? data.etag : etag);
-        const structured = {
-            template_id: typeof data.template_id === 'string' ? data.template_id : template_id,
-            replaced_count: typeof data.replaced_count === 'number' ? data.replaced_count : changedPaths.length,
-            changed_paths: changedPaths,
-            etag: postWriteEtag,
-            new_etag: newEtag,
-            // SOURCES_BINDING-15: surface the dry-run preview flags when the PHP
-            // branch returned them (absent on a real persisted rename).
-            ...(typeof data.dry_run === 'boolean' ? { dry_run: data.dry_run } : {}),
-            ...(typeof data.would_change === 'boolean'
-                ? { would_change: data.would_change }
-                : {}),
-        };
-        const toolkitResult = detailResult({
-            title: 'Source renamed (template-wide)',
-            groups: [
-                {
-                    label: 'Template-wide source/field rename',
-                    entries: [
-                        { key: 'template_id', label: 'Template', value: structured.template_id, format: 'text' },
-                        { key: 'replaced_count', label: 'Bindings changed', value: String(structured.replaced_count), format: 'badge' },
-                        { key: 'new_etag', label: 'New ETag', value: structured.new_etag, format: 'badge', copyable: true },
-                        { key: 'changed_paths', label: 'Changed paths', value: structured.changed_paths.join(', '), format: 'code' },
-                    ],
-                },
-            ],
-        });
-        return structuredResult(toolkitResult, structured);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id },
-            hint: 'On 412 refresh the ETag via yootheme_builder_get_etag and retry. ' +
-                'On 400 invalid_body, pass `from`+`to` (single source rename) and/or ' +
-                '`source_map`/`field_map` (objects of {old: new} name tokens) — at least ' +
-                'one is required. Verify template_id via yootheme_builder_pages_list.',
-        });
-    }
-}
-//# sourceMappingURL=handlers-bind.js.map