@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/tools/elements/handlers-write.js

@@ -0,0 +1,341 @@
+/**
+ * Element-tool write handlers (add/update/move/clone/delete).
+ *
+ * Wave G.4.0 split: read handlers + shared types in `./handlers.ts`.
+ * Wave G.4.1: `handleElementDelete` consults `deps.elicitation` when
+ * `confirm` is undefined — falls back to the explicit preview when
+ * elicitation is unavailable.
+ * Wave G.5: every handler emits 2-phase client-side progress
+ * (`PHASE_SEND` → `PHASE_CONFIRM`) when the caller supplied a
+ * `progressToken` — see `../progress-phases.ts` for the contract.
+ *
+ * @license MIT
+ */
+import { elicitConfirmation } from '@getimo/mcp-toolkit';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
+import { PHASE_CONFIRM, PHASE_SEND } from '../progress-phases.js';
+import { confirmGuard, createProgressReporter, errorResult, jsonResult, } from '../tool-builder.js';
+// ─── Wave-7 (2026-05-29): props validation ──────────────────────────
+//
+// Cold-AI #5 hand-authored `props.source` / `props.source_extended` via
+// element_update_settings({props:{source}}). YT-Pro's render-side then
+// silently ignored the binding because `source` is not a leaf prop — it
+// lives as a SIBLING of `props` on the element node. The agent had no
+// signal that the call was a no-op until visual verification failed.
+//
+// These keys MUST go through yootheme_builder_element_bind_source (which
+// writes them at the correct nesting level). Reject hand-authored attempts
+// up-front so the agent gets a structured error instead of a silent broken
+// render.
+const RESERVED_BINDING_KEYS = new Set([
+    'source',
+    'source_extended',
+    // YT-Pro UI-only placeholders that customers paste from
+    // Inspect/Copy in the visual builder. They never resolve outside the
+    // builder runtime so they're useless inside a stored layout.
+    'source_node',
+]);
+// Wave-7 (2026-05-29): common cold-AI prop-key typos. The PHP backend
+// silently drops unknown props, so a typo like `title` on a headline (real
+// key is `content`) renders an empty headline. We surface a fix suggestion
+// up-front for the small fixed set of high-frequency mistakes.
+//
+// Format: typo → { element_type → canonical_key }
+// element_type === '*' applies to any element where the typo is known to be
+// a typo on every type that has it.
+const COMMON_PROP_TYPOS = {
+    title: {
+        headline: 'content',
+        subtitle: 'content',
+        text: 'content',
+        quote: 'content',
+        button_item: 'content',
+        // Wave-9 F9 (cold-AI #8): `button` accepts `content` at runtime
+        // even though the UI-tab fieldset omits it (see
+        // Inspector::knownAcceptedButHiddenFields). `title` is the most
+        // common cold-AI typo for the button label.
+        button: 'content',
+    },
+    text: {
+        headline: 'content',
+        text: 'content',
+        quote: 'content',
+        // Wave-9 F9: same rationale as `title` above — agents reading
+        // documentation often type `text` for the button label.
+        button: 'content',
+    },
+    label: {
+        button_item: 'content',
+        // Wave-9 F9: `label` is a common cold-AI alias for button text.
+        button: 'content',
+    },
+    url: {
+        button_item: 'link',
+        // Wave-9 F9 (cold-AI #8): `button` accepts `link` at runtime.
+        button: 'link',
+    },
+    href: {
+        // Wave-9 F9: HTML-native authors reach for `href` first.
+        button_item: 'link',
+        button: 'link',
+    },
+    button_text: {
+        button_item: 'content',
+        button: 'content',
+    },
+    button_link: {
+        button_item: 'link',
+        button: 'link',
+    },
+    style: {
+        button_item: 'button_style',
+    },
+    size: {
+        button_item: 'button_size',
+    },
+};
+function detectPropTypos(props, elementType) {
+    if (props === undefined || props === null)
+        return [];
+    const findings = [];
+    for (const key of Object.keys(props)) {
+        const map = COMMON_PROP_TYPOS[key];
+        if (map === undefined)
+            continue;
+        const suggested = map[elementType];
+        if (suggested !== undefined) {
+            findings.push({ typo: key, suggested });
+        }
+    }
+    return findings;
+}
+function rejectOnPropTypos(props, elementType) {
+    const findings = detectPropTypos(props, elementType);
+    if (findings.length === 0)
+        return null;
+    const summary = findings
+        .map((f) => `\`${f.typo}\` → did you mean \`${f.suggested}\`?`)
+        .join('; ');
+    return errorResult({
+        error: new Error(`Unknown prop(s) for element type \`${elementType}\`: ${summary}. ` +
+            'YT-Pro silently drops unknown props server-side, so the element would render empty. ' +
+            'Call yootheme_builder_element_type_get_schema to see the canonical prop keys.'),
+        context: {
+            element_type: elementType,
+            findings,
+        },
+        hint: 'Re-try with the suggested canonical key, or fetch the schema first: ' +
+            `yootheme_builder_element_type_get_schema({ element_type: "${elementType}" }).`,
+    });
+}
+function validatePropsForReservedKeys(props, elementType) {
+    if (props === undefined || props === null)
+        return null;
+    const offending = [];
+    for (const key of Object.keys(props)) {
+        if (RESERVED_BINDING_KEYS.has(key)) {
+            offending.push(key);
+        }
+    }
+    if (offending.length === 0)
+        return null;
+    return errorResult({
+        error: new Error(`Reserved binding key(s) ${offending
+            .map((k) => `\`${k}\``)
+            .join(', ')} are NOT valid props for element type \`${elementType}\`. ` +
+            `Source binding lives as a SIBLING of \`props\` on the element node, ` +
+            `NOT nested inside props. Use \`yootheme_builder_element_bind_source\` ` +
+            `to set the source — it writes the binding at the correct nesting level. ` +
+            `For per-prop leaf bindings (headline.content, etc.) use \`element_bind_source\` ` +
+            `with the prop name in its \`props\` argument.`),
+        context: { element_type: elementType, offending_keys: offending },
+        hint: 'Run yootheme_builder_element_type_get_schema to see the binding contract ' +
+            '(do_not section lists this anti-pattern). Then call element_bind_source.',
+    });
+}
+// ─── element_add ─────────────────────────────────────────────────────
+export async function handleElementAdd({ client }, input, extra) {
+    const { template_id, etag, ...body } = input;
+    // Wave-7: guard against hand-authored source/source_extended in props.
+    const propsRejection = validatePropsForReservedKeys(input.props, input.element_type);
+    if (propsRejection !== null)
+        return propsRejection;
+    // Wave-7: guard against common prop-key typos (title→content etc.).
+    const typoRejection = rejectOnPropTypos(input.props, input.element_type);
+    if (typoRejection !== null)
+        return typoRejection;
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 2, PHASE_SEND);
+    try {
+        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements`, { body, etag });
+        await progress?.report(2, 2, PHASE_CONFIRM);
+        return jsonResult(data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: input,
+            hint: 'On 412 refresh via yootheme_builder_get_etag and retry. On 400 ' +
+                'check `element_type` is valid via yootheme_builder_element_types_list.',
+        });
+    }
+}
+// ─── element_update_settings ─────────────────────────────────────────
+export async function handleElementUpdateSettings({ client }, input, extra) {
+    const { template_id, element_path, props, merge, etag } = input;
+    // Wave-7: guard against hand-authored source/source_extended in props.
+    // element_path is the only identity we have at this layer; the agent gets
+    // a clear message anyway because the offending key is named explicitly.
+    const propsRejection = validatePropsForReservedKeys(props, `<at ${element_path}>`);
+    if (propsRejection !== null)
+        return propsRejection;
+    const encoded = encodeElementPath(element_path);
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 2, PHASE_SEND);
+    try {
+        // T5 / F-12: forward `merge` only when explicitly true so older PHP
+        // builds (which ignore unknown keys anyway) get the same byte-for-
+        // byte body they did before.
+        const body = { props };
+        if (merge === true) {
+            body.merge = true;
+        }
+        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/settings`, { body, etag });
+        await progress?.report(2, 2, PHASE_CONFIRM);
+        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. To merge ' +
+                'props instead of replacing, pass `merge:true` (server deep-merges ' +
+                'the request into current props).',
+        });
+    }
+}
+// ─── element_move ────────────────────────────────────────────────────
+export async function handleElementMove({ client }, input, extra) {
+    const { template_id, element_path, to_parent_path, to_index, etag } = input;
+    const encoded = encodeElementPath(element_path);
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 2, PHASE_SEND);
+    try {
+        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/move`, { body: { to_parent_path, to_index }, etag });
+        await progress?.report(2, 2, PHASE_CONFIRM);
+        return jsonResult(data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, element_path, to_parent_path, to_index },
+            hint: 'Verify destination parent accepts the element type. On 412 refresh ' +
+                'ETag and retry.',
+        });
+    }
+}
+// ─── element_clone ───────────────────────────────────────────────────
+export async function handleElementClone({ client }, input, extra) {
+    const { template_id, element_path, etag } = input;
+    const encoded = encodeElementPath(element_path);
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 2, PHASE_SEND);
+    try {
+        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/clone`, { etag });
+        await progress?.report(2, 2, PHASE_CONFIRM);
+        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_delete (destructive — elicitation + confirm-guard) ─────
+//
+// Wave G.4.1 — destructive confirm via MCP elicitation. Progress
+// reports (Wave G.5) only start AFTER the confirm gate clears.
+// Wave-6 R4 (2026-05-29): Defensive truthiness for the confirm gate.
+// Cold-AI #4 reported the gate kept firing despite `confirm:true`. The Zod
+// schema already coerces only strict booleans (anything non-boolean is
+// rejected upstream as invalid_arguments), but we widen the in-handler
+// check to accept the literal string `"true"` / numeric `1` as a safety net
+// in case a future wrapper round-trips the arg through JSON re-encoding.
+function isConfirmedTrue(v) {
+    if (v === true)
+        return true;
+    if (typeof v === 'string' && v.toLowerCase() === 'true')
+        return true;
+    if (typeof v === 'number' && v === 1)
+        return true;
+    return false;
+}
+function isConfirmedFalse(v) {
+    if (v === false)
+        return true;
+    if (typeof v === 'string' && v.toLowerCase() === 'false')
+        return true;
+    if (typeof v === 'number' && v === 0)
+        return true;
+    return false;
+}
+async function resolveDeleteConfirm(elicitation, template_id, element_path, confirm) {
+    // Wave-6 R4: explicit truthy check — confirm:true (any form) bypasses
+    // the elicitation/preview path immediately.
+    if (isConfirmedTrue(confirm))
+        return null;
+    if (isConfirmedFalse(confirm) || !elicitation) {
+        return confirmGuard({
+            operation: 'delete element',
+            details: {
+                template_id,
+                element_path,
+                // R4: echo back what was received so the agent can compare.
+                // Wave-7 (2026-05-29): force-encode undefined to null so the
+                // key survives JSON.stringify in the agent-facing payload.
+                // Without this the agent saw NO received_confirm field at all
+                // (key dropped by serializer) and could not diff sent vs
+                // received — looked like the value was accepted.
+                received_confirm: confirm === undefined ? null : confirm,
+                expected: 'confirm: true (boolean)',
+            },
+        });
+    }
+    const accepted = await elicitConfirmation(elicitation, `Permanently delete element at "${element_path}" in template ` +
+        `"${template_id}"? This cannot be undone.`);
+    return accepted
+        ? null
+        : confirmGuard({
+            operation: 'delete element',
+            details: { template_id, element_path },
+        });
+}
+export async function handleElementDelete({ client, elicitation }, input, extra) {
+    const { template_id, element_path, etag, confirm } = input;
+    const blocked = await resolveDeleteConfirm(elicitation, template_id, element_path, confirm);
+    if (blocked)
+        return blocked;
+    const encoded = encodeElementPath(element_path);
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 2, PHASE_SEND);
+    try {
+        // Wave-12 / Cold-AI #5 F13 (restored Wave-13 post-merge): forward
+        // `{confirm:true}` as JSON body so the PHP confirm-guard accepts the
+        // delete. Without it the guard returns `requires_confirm:true` and
+        // the caller loops forever.
+        const data = await client.delete(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}`, { etag, body: { confirm: true } });
+        await progress?.report(2, 2, PHASE_CONFIRM);
+        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. On 404 the ' +
+                'element may already be gone — verify with yootheme_builder_element_list.',
+        });
+    }
+}
+//# sourceMappingURL=handlers-write.js.map

package/dist/tools/elements/handlers-write.js.map

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

package/dist/tools/elements/handlers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Element-tool read handlers + shared types/schemas.
+ *
+ * Split out of the original `src/tools/elements.ts` (Wave G.4.0). Write
+ * handlers (add/update/move/clone/delete) live in `./handlers-write.ts`
+ * to keep each file under the 200-LoC budget.
+ *
+ * Handler responsibilities:
+ *   - call the REST endpoint via `deps.client`,
+ *   - map REST data to the toolkit output builders (`tableResult`,
+ *     `detailResult`),
+ *   - wrap in `structuredResult` to carry the typed
+ *     `structuredContent` payload,
+ *   - on error, return `errorResult` with `context` + `hint`.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { type RestClient } from '../../client.js';
+import type { McpServerWithElicitation } from '../elicitation.js';
+import { type ToolResult } from '../tool-builder.js';
+export declare const ELEMENT_LIST_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        rel_path: z.ZodOptional<z.ZodString>;
+        element_type: z.ZodOptional<z.ZodString>;
+        parent_path: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        has_binding: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    total: z.ZodNumber;
+    template_id: z.ZodString;
+    next_cursor: z.ZodOptional<z.ZodString>;
+    projected_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    available_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    unknown_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ELEMENT_GET_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    element_path: z.ZodString;
+    element_type: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    children_count: z.ZodNumber;
+}, z.core.$strip>;
+export interface ElementsHandlerDeps {
+    readonly client: RestClient;
+    /**
+     * Optional MCP elicitation capability. When present, destructive
+     * tools (`element_delete`) prompt the user for confirmation via the
+     * elicitation channel instead of demanding an explicit
+     * `confirm: true` round-trip. When absent, tools fall back to the
+     * preview-then-retry flow.
+     */
+    readonly elicitation?: McpServerWithElicitation;
+}
+export declare function handleElementList({ client }: ElementsHandlerDeps, { template_id, fields, root_path, depth, limit, cursor, }: {
+    template_id: string;
+    fields?: readonly string[];
+    root_path?: string;
+    depth?: number;
+    limit?: number;
+    cursor?: string;
+}): Promise<ToolResult>;
+export declare function handleElementGet({ client }: ElementsHandlerDeps, { template_id, element_path }: {
+    template_id: string;
+    element_path: string;
+}): Promise<ToolResult>;
+export { handleElementAdd, handleElementClone, handleElementDelete, handleElementMove, handleElementUpdateSettings, } from './handlers-write.js';
+//# sourceMappingURL=handlers.d.ts.map

package/dist/tools/elements/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/tools/elements/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAalE,OAAO,EAGH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;iBA6DrC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;iBAOpC,CAAC;AAIH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAsDD,wBAAsB,iBAAiB,CACnC,EAAE,MAAM,EAAE,EAAE,mBAAmB,EAC/B,EACI,WAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,KAAK,EACL,MAAM,GACT,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,GACF,OAAO,CAAC,UAAU,CAAC,CAgIrB;AAID,wBAAsB,gBAAgB,CAClC,EAAE,MAAM,EAAE,EAAE,mBAAmB,EAC/B,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CA8CrB;AAGD,OAAO,EACH,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,2BAA2B,GAC9B,MAAM,qBAAqB,CAAC"}