@wootsup/yt-builder-mcp 1.11.0 → 1.12.0

package/dist/tools/elements/schema-validation.d.ts

@@ -5,7 +5,7 @@
  * `./handlers-write.ts` only catch a small fixed set of known mistakes. An
  * unknown prop key that is NOT in those tables slips through, the PHP backend
  * silently drops it, and the element renders empty with no signal to the agent
- * (Glöckle B3).
+ * (customer B3).
  *
  * This module adds a LIVE cross-check against the element-type's real schema:
  * the authoritative prop keys are `fields[].name` from
@@ -66,18 +66,49 @@ export declare function nearestFieldName(key: string, fields: readonly string[])
  */
 export declare function suggestFieldNames(key: string, fields: readonly string[]): string[];
 /**
- * Pull `fields[].name` out of the element-type schema response. Mirrors the
- * envelope handling in `../inspection.ts`: the type schema nests under
- * `schema`, with a top-level fallback for older backends.
+ * Ordering-red-border fix (2026-07-25) — the full per-field wire shape, as
+ * opposed to `extractSchemaFieldNames`' bare name list. `enum`/`default` were
+ * previously fetched by every caller (via `fields[].name` extraction) and then
+ * DISCARDED — this is what `element_add`'s required-enum default-seeding and
+ * explicit-invalid-enum-value hard-reject (`seedRequiredEnumDefaults` /
+ * `validateEnumPropValues`, below) need to do their job.
+ */
+export interface SchemaField {
+    readonly name: string;
+    readonly type?: string;
+    /** Normalised to `list<string>` server-side (`Inspector::extractEnum`); absent when the field has no dropdown/select options. */
+    readonly enum?: readonly string[];
+    /** `mixed` server-side; absent when the field declares no schema default. */
+    readonly default?: unknown;
+}
+/**
+ * Pull the full `fields[]` list out of the element-type schema response.
+ * Mirrors the envelope handling in `../inspection.ts`: the type schema nests
+ * under `schema`, with a top-level fallback for older backends.
+ *
+ * @returns the field list (possibly empty), or `null` when the response
+ *   carries no `fields` array at all (unknown schema shape → treat as unknown).
+ */
+export declare function extractSchemaFields(data: unknown): SchemaField[] | null;
+/**
+ * Pull `fields[].name` out of the element-type schema response. Thin
+ * name-only projection of {@link extractSchemaFields} — kept as its own
+ * export because every EXISTING caller/test only needs the name list.
  *
  * @returns the field-name list (possibly empty), or `null` when the response
  *   carries no `fields` array at all (unknown schema shape → treat as unknown).
  */
 export declare function extractSchemaFieldNames(data: unknown): string[] | null;
 /**
- * Best-effort fetch of an element-type's real prop keys. ANY failure (network,
- * non-2xx, unknown shape) resolves to `null` so the caller falls through to the
- * prior behaviour — a schema fetch must never break the write.
+ * Best-effort fetch of an element-type's full field schema. ANY failure
+ * (network, non-2xx, unknown shape) resolves to `null` so the caller falls
+ * through to the prior behaviour — a schema fetch must never break the write.
+ */
+export declare function fetchSchemaFields(client: RestClient, elementType: string): Promise<SchemaField[] | null>;
+/**
+ * Best-effort fetch of an element-type's real prop keys. Name-only
+ * projection of {@link fetchSchemaFields} — kept as its own export for
+ * existing callers that only need the key list.
  */
 export declare function fetchSchemaFieldNames(client: RestClient, elementType: string): Promise<string[] | null>;
 /**
@@ -92,5 +123,96 @@ export declare function validatePropsAgainstLiveSchema(opts: {
     readonly elementType: string;
     readonly props: Record<string, unknown> | undefined;
     readonly reservedKeys: ReadonlySet<string>;
+    /**
+     * Ordering-red-border fix (2026-07-25): reuse an ALREADY-fetched live
+     * schema (e.g. `element_add`'s default-seeding fetches it anyway) instead
+     * of a second network round-trip for the SAME element_type. `undefined`
+     * (the omitted default) preserves the original behaviour — this function
+     * fetches for itself. Passing `null` explicitly means "already fetched
+     * and it failed / was uncertain" and short-circuits to the same
+     * fall-through as a failed fetch, with no network call.
+     */
+    readonly fields?: readonly SchemaField[] | null;
 }): Promise<ToolResult | null>;
+/**
+ * A field is "required" in the same sense the PHP-side `UiInvariantValidator`
+ * uses for its `required_field_empty` violation: it is enum-constrained (a
+ * non-empty `enum` list) and that list does NOT contain `''` — an optional
+ * select always lists `''` as its "nothing selected" member.
+ */
+export declare function isRequiredEnumField(field: SchemaField): boolean;
+/**
+ * Seed every REQUIRED enum field (see {@link isRequiredEnumField}) that
+ * declares a non-empty schema `default` and is ABSENT from `props` with that
+ * default — mirroring what YOOtheme's own native element-creation
+ * initialises. A field the caller already supplied a key for (any value,
+ * including one later hard-rejected by {@link validateEnumPropValues}) is
+ * never touched: the caller's own value ALWAYS wins, no coercion, ever. An
+ * element type with no schema default for a field gets nothing invented for
+ * it — the seed set only ever pulls from real schema data.
+ *
+ * Returns `props` UNCHANGED (same reference, possibly `undefined`) when
+ * there is nothing to seed, so a no-op call never allocates a new object.
+ */
+export declare function seedRequiredEnumDefaults(fields: readonly SchemaField[], props: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Hard-reject a prop VALUE the caller explicitly supplied for a KNOWN
+ * enum-constrained field when that value is not one of the field's declared
+ * `enum` members. `validatePropsAgainstLiveSchema` only ever checks that a
+ * prop KEY is known — this is the VALUE half, scoped to element_add's create
+ * path only (see the section banner above for why).
+ *
+ * An empty value (`''` / `null` / `undefined`) is deliberately NOT judged
+ * here — persisting an empty value on a required field is a DIFFERENT
+ * violation (`required_field_empty`) the PHP write guard already owns; this
+ * function only judges a genuinely non-empty value against enum membership.
+ * A non-scalar value (a dynamic-binding shape) is skipped — it cannot be
+ * safely compared against a string enum and is not this function's concern.
+ *
+ * Returns `null` (pass) whenever the field is unknown to the given `fields`
+ * list or is not enum-constrained — this is a value check layered ON TOP of
+ * the key check, never a whitelist on its own.
+ */
+export declare function validateEnumPropValues(opts: {
+    readonly elementType: string;
+    readonly fields: readonly SchemaField[];
+    readonly props: Record<string, unknown> | undefined;
+    readonly reservedKeys: ReadonlySet<string>;
+}): ToolResult | null;
+/** A non-blocking note attached to a SUCCESSFUL write. */
+export interface HeaderTransparencyWarning {
+    readonly code: string;
+    readonly message: string;
+}
+export interface HeaderTransparencyGuardOutcome {
+    /** A hard reject (class A), or `null` when the write may proceed. */
+    readonly rejection: ToolResult | null;
+    /**
+     * The props to actually send — the SAME reference when nothing was seeded,
+     * so a no-op call never allocates and a byte-identical body is preserved.
+     */
+    readonly props: Record<string, unknown> | undefined;
+    readonly warnings: readonly HeaderTransparencyWarning[];
+}
+/**
+ * Guard a props write against the transparent-header failure modes.
+ *
+ * Pure: takes the write's own payload (plus its merge/unset semantics) and
+ * returns a rejection, the props to send, and any warnings. No I/O — it never
+ * needs the element type either, because the three props are namespaced and
+ * exist on `section` alone.
+ */
+export declare function guardHeaderTransparencyWrite(opts: {
+    readonly props: Record<string, unknown> | undefined;
+    /** `true` = server-side deep merge; anything else = full replace (the default). */
+    readonly merge?: boolean;
+    readonly unset?: readonly string[];
+    readonly elementPath: string;
+}): HeaderTransparencyGuardOutcome;
+/**
+ * Merge client-side warnings into a REST response body so a successful write
+ * still carries them. A non-object body (or an empty warning list) is returned
+ * untouched, so nothing that has no place to put them is reshaped.
+ */
+export declare function withHeaderTransparencyWarnings(data: unknown, warnings: readonly HeaderTransparencyWarning[]): unknown;
 //# sourceMappingURL=schema-validation.d.ts.map

package/dist/tools/elements/schema-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../../../src/tools/elements/schema-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAErF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,GAAG,SAAS,CAkBpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CAmBV;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,IAAI,CAiBtE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACvC,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAS1B;AAED;;;;;;GAMG;AACH,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACvD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9C,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAiE7B"}
+{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../../../src/tools/elements/schema-validation.ts"],"names":[],"mappings":"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"}