@wootsup/yt-builder-mcp 1.11.0 → 2.0.0

package/dist/tools/pages/handlers-read.js

@@ -1,929 +0,0 @@
-/**
- * Page-tool READ handlers + shared output-schemas.
- *
- * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) to keep
- * each file ≤ 200 LoC per Architecture §11. Write handlers (page_save,
- * page_publish — 3-phase progress contract) live in `./handlers-write.ts`.
- *
- * @license MIT
- */
-import { detailResult, tableResult } from '@getimo/mcp-toolkit';
-import { encodeTemplateId } from '../../client.js';
-import { RestError } from '../../errors.js';
-import { flattenLayout } from '../layout-flatten.js';
-import { PAGES_COMPACT_COLUMNS, PAGES_TABLE_COLUMNS, SCHEMA_COMPACT_COLUMNS, SCHEMA_TABLE_COLUMNS, buildEtagDetail, buildOutlineText, buildRenderPreviewDetail, buildSchemaRows, mapPageRow, } from '../format/pages-format.js';
-import { DEFAULT_FIELDS_PAGES_LIST, DEFAULT_FIELDS_SCHEMA, applyMaxChars, clipTextWindow, columnsFromFields, decodeOffsetCursor, encodeOffsetCursor, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, } from '../sparse-fields.js';
-import { errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
-import { TARGET_KEYS } from './schemas.js';
-import { appendTargetParams, malformedTargetError, normalizeTarget, serverTooOldError, TARGET_FAILURE_HINT, targetKeysOf, tooManyTargetsError, } from './target.js';
-// ─── pages_list ─────────────────────────────────────────────────────
-/** Default page size for pages_list when `limit` is omitted (B2). */
-const DEFAULT_PAGES_LIMIT = 50;
-/**
- * SOURCES_BINDING-29 / DISCOVERY_AUDIT-18 — the STATIC pages_list field
- * vocabulary. `mapPageRow` always emits the SAME key set on every row, so
- * deriving it once from an empty-row projection gives the authoritative
- * discoverable field list WITHOUT hard-coding a list that could drift from the
- * mapper. Used to (a) validate a caller's `fields[]` against the real schema
- * rather than against whatever rows a (possibly empty) result happened to carry,
- * and (b) emit `available_fields` on every call. Sorted for a stable echo.
- */
-const PAGES_LIST_KNOWN_FIELDS = Object.keys(mapPageRow({})).sort();
-/** Decode an offset cursor (`base64url("o:<n>")` or raw `o:<n>`) → offset, else 0. */
-function decodePagesCursor(cursor) {
-    if (cursor === undefined || cursor === '')
-        return 0;
-    let raw = cursor;
-    if (!/^o:\d+$/.test(cursor)) {
-        try {
-            raw = Buffer.from(cursor.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
-        }
-        catch {
-            return 0;
-        }
-    }
-    const m = /^o:(\d+)$/.exec(raw);
-    return m ? Number(m[1]) : 0;
-}
-function encodePagesCursor(offset) {
-    return Buffer.from(`o:${offset}`, 'utf8').toString('base64url');
-}
-/** Case-insensitive substring match across a page row's label / id / type. */
-function matchesPageFilter(row, needle) {
-    const hay = `${String(row.label ?? '')} ${String(row.id ?? '')} ${String(row.type ?? '')}`.toLowerCase();
-    return hay.includes(needle);
-}
-export async function handlePagesList(client, { fields, limit, cursor, label_contains, max_chars, }) {
-    try {
-        // G-B (Glöckle 2026-06-26, P0): forward `limit`/`offset`/`filter` to the
-        // REST /pages endpoint so a site with hundreds of templates does not
-        // serialize the full set every call (server-side pagination). The
-        // server is BACKWARD-COMPATIBLE: with no params it returns the full set
-        // (the pre-G-B shape), so the client-side slice below stays a correct
-        // fallback for an un-upgraded host that ignores the params. When the
-        // server DOES honour them it echoes `total` (the filtered grand total)
-        // + `returned`; we trust that `total` over the local slice length so
-        // the cursor still spans the whole result.
-        const offset = decodePagesCursor(cursor);
-        const qs = new URLSearchParams();
-        if (typeof limit === 'number')
-            qs.set('limit', String(limit));
-        if (offset > 0)
-            qs.set('offset', String(offset));
-        if (label_contains !== undefined && label_contains !== '') {
-            qs.set('label_contains', label_contains);
-        }
-        const query = qs.toString();
-        const data = await client.get(`/pages${query !== '' ? `?${query}` : ''}`);
-        const rawPages = Array.isArray(data.pages) ? data.pages : [];
-        let mapped = rawPages
-            .filter((x) => x !== null && typeof x === 'object')
-            .map(mapPageRow);
-        // B2 (Glöckle 2026-06-25) + G-B server-side fallback: a real site can
-        // have hundreds of templates. When the server already paged + filtered
-        // (it echoes a `total`), the rows it returned ARE the page — do NOT
-        // re-slice them. When the server ignored the params (no `total`, full
-        // set returned) we still filter + slice CLIENT-SIDE so behaviour is
-        // identical against an un-upgraded host. Filter BEFORE paging so
-        // `total` + the cursor reflect the filtered result.
-        const serverPaged = typeof data.total === 'number';
-        if (!serverPaged && label_contains !== undefined && label_contains !== '') {
-            const needle = label_contains.toLowerCase();
-            mapped = mapped.filter((row) => matchesPageFilter(row, needle));
-        }
-        const pageSize = limit ?? DEFAULT_PAGES_LIMIT;
-        // Server-paged: rows ARE the slice, total comes from the server.
-        // Client-fallback: slice the full set locally.
-        const slice = serverPaged ? mapped : mapped.slice(offset, offset + pageSize);
-        const total = serverPaged ? data.total : mapped.length;
-        const nextOffset = offset + slice.length;
-        const nextCursor = nextOffset < total ? encodePagesCursor(nextOffset) : undefined;
-        // B1: project the SLICE (text leg + structuredContent) when fields given.
-        const items = projectFields(slice, fields, DEFAULT_FIELDS_PAGES_LIST);
-        const hasExplicitFields = Array.isArray(fields) && fields.length > 0;
-        // SOURCES_BINDING-29: validate `fields[]` against the STATIC schema, not
-        // the returned rows — an EMPTY result set no longer makes every field
-        // look invalid (the "available: " with no fields bug). unknown = a
-        // requested field whose top-level segment is not a known key.
-        const unknownFields = hasExplicitFields
-            ? fields.filter((f) => !PAGES_LIST_KNOWN_FIELDS.includes(f.split('.')[0] ?? f))
-            : [];
-        // DISCOVERY_AUDIT-18: `available_fields` is the STATIC discoverable
-        // vocabulary, emitted on EVERY call (an empty page still tells the agent
-        // which fields exist). `projected_fields` reflects the keys ACTUALLY in
-        // the emitted rows — the full vocabulary in the default no-`fields` case,
-        // the requested subset otherwise (LAYOUT_READ-18: no longer the stale
-        // 5-key DEFAULT echo while rows carry 11).
-        const availableFields = [...PAGES_LIST_KNOWN_FIELDS];
-        const projectedFields = hasExplicitFields
-            ? [...fields]
-            : [...PAGES_LIST_KNOWN_FIELDS];
-        // SOURCES_BINDING-29: suppress the loud projection warning on an empty
-        // result (projection is moot) and when nothing is actually unknown.
-        const emitWarning = total > 0 && unknownFields.length > 0;
-        const unknownNote = emitWarning
-            ? ` (unknown projection fields ignored: ${unknownFields.join(', ')}` +
-                ` — available: ${availableFields.join(', ')})`
-            : '';
-        const useProjection = hasExplicitFields;
-        const projectedColumns = useProjection ? columnsFromFields([...fields]) : undefined;
-        const pagedNote = total > slice.length ? ` of ${String(total)}${nextCursor !== undefined ? ', pass cursor for more' : ''}` : '';
-        const toolkitResult = tableResult(useProjection ? items : slice, {
-            columns: projectedColumns ?? [...PAGES_TABLE_COLUMNS],
-            compactColumns: projectedColumns ?? [...PAGES_COMPACT_COLUMNS],
-            header: (count) => `${String(count)}${pagedNote} pages${unknownNote}`,
-            footer: 'Use yootheme_builder_page_get_schema <id> to inspect.',
-        });
-        return structuredResult(applyMaxChars(toolkitResult, max_chars), {
-            items,
-            total,
-            returned: slice.length,
-            ...(nextCursor !== undefined ? { next_cursor: nextCursor } : {}),
-            ...(typeof data.etag === 'string' ? { etag: data.etag } : {}),
-            projected_fields: projectedFields,
-            available_fields: availableFields,
-            // Emit unknown_fields whenever the caller passed an explicit
-            // projection (empty [] = all valid; keeps the F-004 contract), omit
-            // it on the default no-`fields` call.
-            ...(hasExplicitFields ? { unknown_fields: unknownFields } : {}),
-            ...(emitWarning ? { projection_warning: unknownNote.trim() } : {}),
-        });
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: {},
-            hint: 'Run yootheme_builder_diagnose to verify connectivity and auth.',
-        });
-    }
-}
-/**
- * G-A (Track-C URL→layout): GET /pages/resolve?url=... → the per-page
- * `template_id` that renders the URL. Returns the structured result on a
- * 200; throws (RestError 404) when the URL renders via a theme template or
- * carries no YT per-page layout — the caller surfaces the steer-to-pages_list
- * hint. Shared by the `pages_resolve` tool AND the `url`-param fast-path in
- * page_get_layout / page_get_schema (one internal REST call → one MCP call
- * yields the layout).
- */
-export async function resolveUrlToTemplate(client, url) {
-    return client.get(`/pages/resolve?url=${encodeURIComponent(url)}`);
-}
-/**
- * A-6: resolve a semantic `target` — `GET /pages/resolve?target[special]=home`.
- * The bracket encoding is the ONE wire form both CMS controllers parse (see
- * `./target.ts`).
- */
-async function resolveTargetToTemplate(client, target) {
-    const qs = new URLSearchParams();
-    appendTargetParams(qs, target);
-    return client.get(`/pages/resolve?${qs.toString()}`);
-}
-/**
- * A-6: is this failure an OLD host rejecting the request because it still
- * hard-requires `url`? WP core answers `rest_missing_callback_param` when the
- * route arg is `required`; the pre-A-5 controller answered its own
- * `missing_url`. Either way the fix is "update the plugin", not "fix your
- * target" — and only ever on a target-only call.
- */
-function isMissingUrlRejection(e) {
-    if (!(e instanceof RestError) || e.status !== 400)
-        return false;
-    const code = e.code ?? '';
-    return code.includes('rest_missing_callback_param') || code.includes('missing_url');
-}
-/** A-6: narrow an off-the-wire `matched_by` to the declared enum, else drop it. */
-function knownMatchedBy(value) {
-    return TARGET_KEYS.find((key) => key === value);
-}
-export async function handlePagesResolve(client, { url, target }) {
-    // A-6 / F205: the exactly-one-of(url, target) contract is validated HERE
-    // with typed results — a zod `.refine` would surface as a raw -32602 and
-    // strip every hint below. Mirrors the WP/Joomla controllers' own codes so
-    // the contract reads the same whether it fired locally or upstream.
-    const resolvedTarget = normalizeTarget(target);
-    // BUG-4 (shared rule, PHP `PageQuery::malformedTargetError()`): a target bag
-    // that survived nothing is a MALFORMED ADDRESS. Checked BEFORE the
-    // exactly-one-of(url, target) pair, exactly as both controllers do — so it
-    // is never reported as `missing_url` (which claims no address was passed)
-    // and, alongside a `url`, is never silently ignored.
-    const malformed = malformedTargetError(target, resolvedTarget, {
-        context: { url: url ?? null, target: target ?? null },
-        hint: 'Each target member must be a non-empty string or number — e.g. '
-            + 'target:{special:"home"} or target:{template_id:"page:4816"}. Or pass `url` instead.',
-    });
-    if (malformed !== null)
-        return malformed;
-    const targetKeys = targetKeysOf(resolvedTarget);
-    const hasUrl = typeof url === 'string' && url.trim() !== '';
-    const hasTarget = targetKeys.length > 0;
-    if (hasUrl && hasTarget) {
-        return tooManyTargetsError({
-            supplied: ['url', ...targetKeys.map((k) => `target.${k}`)],
-            context: { url: url ?? null, target: resolvedTarget },
-        });
-    }
-    if (targetKeys.length > 1) {
-        return tooManyTargetsError({
-            supplied: targetKeys,
-            context: { target: resolvedTarget },
-        });
-    }
-    if (!hasUrl && !hasTarget) {
-        return errorResult({
-            error: new RestError({
-                status: 400,
-                code: 'yootheme_builder_mcp.pages.missing_url',
-                message: 'A page address is required: pass `url` or `target`.',
-                body: null,
-            }),
-            context: { url: null, target: {} },
-            hint: 'Pass `url` (a public page/article URL), or `target` with exactly one of ' +
-                'template_id / post_id / url / special ("home", "blog", "404", "search", ' +
-                '"category", "tag", "author", "archive") / title.',
-        });
-    }
-    try {
-        const data = hasTarget
-            ? await resolveTargetToTemplate(client, resolvedTarget)
-            : await resolveUrlToTemplate(client, (url ?? '').trim());
-        const matchedBy = knownMatchedBy(data.matched_by);
-        return structuredResult(jsonResult(data), {
-            template_id: data.template_id,
-            // G-A2: post_id is null for a theme-template resolution.
-            post_id: data.post_id ?? null,
-            type: data.type,
-            // Forwarded ONLY when the host sent one — a synthesised label would
-            // claim a page name this build has no way to know.
-            ...(typeof data.label === 'string' && data.label !== '' ? { label: data.label } : {}),
-            frontend_url: data.frontend_url ?? null,
-            // G-A2: context/resolved_via are additive. An OLDER plugin (pre-G-A2)
-            // only ever resolved per-page layouts and omits both — default to the
-            // per-page shape so a strict host still accepts the success.
-            context: data.context ?? null,
-            resolved_via: data.resolved_via ?? 'per_page',
-            // A-6: forwarded ONLY when the host sent a value this build knows.
-            // A `url` resolve and every pre-A-5 host omit it; an UNKNOWN token
-            // from a newer host is dropped rather than tripping the strict
-            // outputSchema and failing an otherwise perfect resolve.
-            ...(matchedBy !== undefined ? { matched_by: matchedBy } : {}),
-        });
-    }
-    catch (e) {
-        // A-6 version-skew: an old host still hard-requires `url`, so a
-        // target-only call 400s before its controller ever sees the target.
-        // That is an "update the plugin" condition, not a bad address.
-        if (hasTarget && isMissingUrlRejection(e)) {
-            return serverTooOldError({
-                message: 'This site rejected a `target`-only resolve because it still requires `url`.',
-                context: { target: resolvedTarget },
-            });
-        }
-        return errorResult({
-            error: e,
-            context: { url: url ?? null, target: resolvedTarget },
-            // BUG-3 / MM-5: the target-aware hint now lives in `target.js` so
-            // `pages_audit` answers the SAME error family with the SAME steer.
-            hint: hasTarget
-                ? TARGET_FAILURE_HINT
-                : 'If this 404s, the URL renders via a theme template (not a ' +
-                    'per-page layout) — use yootheme_builder_pages_list to find its ' +
-                    'template_id. Verify the URL is a public, singular page/article.',
-        });
-    }
-}
-// ─── page_get_layout ────────────────────────────────────────────────
-/**
- * F195 (P0, 2026-06-12) — per-process layout-read dedup cache.
- *
- * The Desktop-E2E #2 forensic showed two identical 84 KB full-layout dumps in
- * a single session (58 % of the 330 KB output budget). The same agent re-read
- * the SAME template at the SAME state — the second dump was pure waste. This
- * module-internal cache records, keyed by `site|template_id`, the LAST etag
- * served as a FULL read. On a subsequent full read whose server-returned etag
- * matches, the handler short-circuits with a one-line `[unchanged]` notice
- * instead of re-emitting the body. `force:true` bypasses; bindings_only reads
- * are never deduped (they are already cheap and are the recommended path).
- *
- * Cache key includes the site so multi-site sessions never cross-contaminate.
- * It is a plain module Map (process-scoped) — exactly the granularity the
- * forensic targets (duplicate reads within one MCP session).
- */
-const layoutDedupCache = new Map();
-/** Test-only: clear the dedup cache between cases (mirrors the bus reset idiom). */
-export function __resetLayoutDedupCacheForTests() {
-    layoutDedupCache.clear();
-}
-/**
- * Single SSoT unwrap rule for `page_get_layout(flat:true)`.
- *
- * flattenLayout iterates the TOP-LEVEL ENTRIES of whatever it is given.
- * That is correct for a *container* (an array, or an index-keyed object
- * `{0:{...},1:{...}}`) where every entry is itself an element node. It
- * is WRONG for a single root NODE (`{type:'layout', children:[...]}`),
- * whose top-level entries are `type` / `children` / `version` — not
- * element nodes. Handing a root node straight to flattenLayout emits
- * nothing (the C4 / Wave-9 F7 silent-`elements:[]` bug class).
- *
- * Rule: a value that looks like a single root node (`type === 'layout'`
- * with an array `children`) is unwrapped to its `.children` array; any
- * other value passes through untouched so containers and the legacy
- * index-keyed object shape keep working unchanged.
- */
-function unwrapToWalkableContainer(value) {
-    if (value !== null &&
-        typeof value === 'object' &&
-        !Array.isArray(value)) {
-        const obj = value;
-        if (obj.type === 'layout' && Array.isArray(obj.children)) {
-            return obj.children;
-        }
-    }
-    return value;
-}
-/**
- * Decide whether a ZERO-element flatten should surface the C4
- * "layout shape not recognized" warning.
- *
- * The decision runs on the RESOLVED walk container (`layoutRoot`, the value
- * actually handed to `flattenLayout` after `unwrapToWalkableContainer`),
- * NOT the raw `data.layout` envelope. That is the F29 calibration
- * (2026-06-10):
- *
- *   - An ARRAY (empty or otherwise) is a recognized container shape. A
- *     bare root node `{type:'layout', children:[]}` (a freshly-created
- *     empty article / per-page layout, or a fresh empty theme template)
- *     unwraps to its empty `.children` array, so it lands here and is
- *     treated as a GENUINELY empty page → NO warning. This kills the
- *     false-positive the raw-envelope check produced (the bare root node
- *     is a non-empty OBJECT — keys `type`/`children` — so the old check
- *     mistook "empty container" for "had content").
- *   - An OBJECT with ZERO keys (e.g. an empty index-keyed container `{}`)
- *     is also genuinely empty → NO warning.
- *   - An OBJECT with keys that nonetheless flattened to nothing is an
- *     unrecognized / future shape masquerading as empty → WARN (the
- *     original C4 contract; the `{some_future_key, another}` fixture).
- *
- * @param layoutRoot The resolved walk container passed to flattenLayout.
- */
-function isUnrecognizedNonEmptyLayout(layoutRoot) {
-    if (Array.isArray(layoutRoot)) {
-        // Recognized container shape — empty or not, never "unrecognized".
-        return false;
-    }
-    if (layoutRoot !== null && typeof layoutRoot === 'object') {
-        // A non-empty object that produced zero elements is the
-        // unrecognized-shape case worth warning about; an empty object is
-        // a genuinely empty container.
-        return Object.keys(layoutRoot).length > 0;
-    }
-    return false;
-}
-/**
- * G-A (Track-C URL→layout): resolve the EFFECTIVE template_id a read tool
- * should operate on from the three accepted addressing modes, so ONE MCP
- * tool call reaches a layout from any of them:
- *
- *   - `template_id` (highest precedence) — used verbatim.
- *   - `post_id`     — `String(post_id)` is a bare numeric id the server's C1
- *                     dispatch resolves to the per-page layout. No extra REST
- *                     round-trip.
- *   - `url`         — resolved via GET /pages/resolve first (one internal REST
- *                     call), then the returned `template_id` is used.
- *
- * Exactly one of the three is required. When `url` does not resolve (theme-
- * template / non-singular URL), the resolve error (with its steer-to-pages_list
- * hint) is returned for the caller to surface unchanged.
- */
-async function resolveEffectiveTemplateId(client, args) {
-    if (args.template_id !== undefined && args.template_id !== '') {
-        return { templateId: args.template_id };
-    }
-    if (args.post_id !== undefined) {
-        return { templateId: String(args.post_id) };
-    }
-    if (args.url !== undefined && args.url !== '') {
-        try {
-            const resolved = await resolveUrlToTemplate(client, args.url);
-            return { templateId: resolved.template_id };
-        }
-        catch (e) {
-            return {
-                error: errorResult({
-                    error: e,
-                    context: { url: args.url },
-                    hint: 'This URL did not resolve to a per-page layout or a governing ' +
-                        'theme template (home/front-page/search/date are not mapped). ' +
-                        'Use yootheme_builder_pages_list to find its template_id.',
-                }),
-            };
-        }
-    }
-    return {
-        error: errorResult({
-            error: new Error('one of template_id, post_id, or url is required'),
-            context: {},
-            hint: 'Pass template_id (from pages_list), OR post_id (a numeric ' +
-                'WP post-id / Joomla article-id), OR url (a public page URL).',
-        }),
-    };
-}
-/**
- * G1 (V3): coerce the REST `nodes` field into a typed `OutlineNode[]` for the
- * pure render sidecar. The wire shape is the canonical `PageQuery::outline()`
- * projection (depth/label/type/handle/path/bound); this guard tolerates a
- * malformed or absent field by emitting an empty list rather than throwing,
- * so an unexpected payload degrades to an empty outline (never a 500).
- */
-function parseOutlineNodes(raw) {
-    if (!Array.isArray(raw)) {
-        return [];
-    }
-    const out = [];
-    for (const item of raw) {
-        if (item === null || typeof item !== 'object') {
-            continue;
-        }
-        const n = item;
-        const boundRaw = n.bound;
-        let bound = null;
-        if (boundRaw !== null && typeof boundRaw === 'object') {
-            const b = boundRaw;
-            bound = {
-                query_name: typeof b.query_name === 'string' ? b.query_name : '',
-                has_condition: b.has_condition === true,
-            };
-        }
-        out.push({
-            depth: typeof n.depth === 'number' && Number.isFinite(n.depth) ? Math.trunc(n.depth) : 0,
-            label: typeof n.label === 'string' ? n.label : '',
-            type: typeof n.type === 'string' ? n.type : 'unknown',
-            handle: typeof n.handle === 'string' ? n.handle : '',
-            path: typeof n.path === 'string' ? n.path : '',
-            bound,
-        });
-    }
-    return out;
-}
-/**
- * B7 (Glöckle continuation cursor) — build the full-dump TEXT leg windowed at
- * `[offset, offset+max_chars)` and, when more remains, append a `next_cursor`.
- *
- * The truncated full/bindings_only TEXT leg of page_get_layout had NO
- * continuation: once `max_chars` clipped the JSON dump there was no way to
- * fetch the rest of THAT subtree. This windows the SAME serialized JSON
- * `jsonResult(data)` would emit, slices it from `offset` for up to `max_chars`
- * chars, and emits a `next_cursor` (base64url `o:<n>`, the SAME opaque
- * offset-cursor contract pages_list/sources_list use) when the body is clipped
- * so a follow-up call resumes from the offset. The structured leg carries the
- * cursor + offsets verbatim (page_get_layout declares no outputSchema).
- *
- * `max_chars === undefined` AND `offset === 0` returns the whole body with NO
- * cursor — byte-identical to the pre-B7 `applyMaxChars(jsonResult(data),
- * undefined)` no-op. A final slice (nothing left after it) carries no cursor.
- */
-function windowedFullDump(data, offset, maxChars) {
-    const firstBlock = jsonResult(data).content[0];
-    const fullText = firstBlock !== undefined && firstBlock.type === 'text' && typeof firstBlock.text === 'string'
-        ? firstBlock.text
-        : '';
-    const fullLength = fullText.length;
-    const window = clipTextWindow(fullText, offset, maxChars);
-    const nextCursor = window.clipped ? encodeOffsetCursor(window.nextOffset) : undefined;
-    // The text leg the LLM reads: the windowed slice. When a cursor is emitted
-    // the clip marker already rides inside `window.text`; append the resume
-    // hint so an agent reading ONLY the text leg can still page.
-    const text = nextCursor !== undefined
-        ? `${window.text}\n[continued] pass cursor:"${nextCursor}" to page_get_layout to read chars ` +
-            `${String(window.nextOffset)}–${String(fullLength)} of this layout.`
-        : window.text;
-    return structuredResult({ content: [{ type: 'text', text }] }, {
-        ...data,
-        ...(nextCursor !== undefined ? { next_cursor: nextCursor } : {}),
-        char_offset: window.offset,
-        char_total: fullLength,
-        returned_chars: window.text.length,
-    });
-}
-export async function handlePageGetLayout(client, { template_id, post_id, url, flat, fields, mode, force, cursor, max_chars }) {
-    try {
-        // G-A: resolve the effective template_id from template_id | post_id | url.
-        const effective = await resolveEffectiveTemplateId(client, { template_id, post_id, url });
-        if ('error' in effective) {
-            return effective.error;
-        }
-        const templateId = effective.templateId;
-        // B7 (Glöckle continuation cursor): an opaque char-offset cursor
-        // (base64url `o:<n>`) resumes a previously-clipped full/bindings_only
-        // text leg from the offset. A present cursor makes the read a
-        // CONTINUATION — it is NEVER served from the [unchanged] dedup cache
-        // (the agent is intentionally paging the rest of the dump). `0` (no
-        // cursor / start) keeps the pre-B7 behaviour.
-        const charOffset = decodeOffsetCursor(cursor);
-        const isContinuation = cursor !== undefined && cursor !== '';
-        // F195 (P0): forward `mode=bindings_only` so the server returns the
-        // trimmed binding skeleton the dynamize/bind workflow needs. G1 (V3):
-        // `mode=outline` forwards `?mode=outline` for the flat semantic-outline
-        // node list. `full` (default) appends no query param — byte-identical
-        // to the pre-F195 request shape.
-        const isBindingsOnly = mode === 'bindings_only';
-        const isOutline = mode === 'outline';
-        const query = isBindingsOnly ? '?mode=bindings_only' : isOutline ? '?mode=outline' : '';
-        const data = await client.get(`/pages/${encodeTemplateId(templateId)}/layout${query}`);
-        // G1 (V3): outline is the cheapest projection (and, like bindings_only,
-        // the recommended map-first path), so it is NEVER deduped — the
-        // per-process unchanged-read cache mis-keys on a non-full shape. The
-        // flat `nodes[]` are rendered to indented breadcrumb text via the pure
-        // sidecar; the full structured payload rides along for structured hosts.
-        if (isOutline) {
-            const nodes = parseOutlineNodes(data.nodes);
-            return structuredResult({ content: [{ type: 'text', text: buildOutlineText(nodes) }] }, data);
-        }
-        // F195 (P0): per-process dedup of REPEATED full reads. bindings_only
-        // is already cheap (and the recommended path), so it is never deduped.
-        // The skeleton passes straight through unchanged — EXCEPT B7: when
-        // `max_chars` clips it (or the caller resumes with a `cursor`), it gets
-        // the SAME char-offset continuation window the full leg does, so the
-        // binding skeleton of a very large template is pageable too.
-        if (isBindingsOnly) {
-            if (max_chars !== undefined || isContinuation) {
-                return windowedFullDump(data, charOffset, max_chars);
-            }
-            return jsonResult(data);
-        }
-        const etag = typeof data.etag === 'string' ? data.etag : undefined;
-        const dedupKey = `${client.getPlatform().baseUrl}|${templateId}`;
-        // B7: a WINDOWED read — either a continuation (cursor present) or a
-        // first slice (max_chars set) — must NEVER short-circuit on the
-        // [unchanged] dedup. The agent explicitly wants a (paged) slice of the
-        // body, and the one-line `[unchanged]` notice carries no slice + no
-        // cursor, which would strand the pager. Only the un-windowed full read
-        // is deduped (the forensic's duplicate-84KB waste this guards).
-        const isWindowedRead = isContinuation || max_chars !== undefined;
-        if (!isWindowedRead && force !== true && flat !== true && etag !== undefined) {
-            const lastServed = layoutDedupCache.get(dedupKey);
-            if (lastServed === etag) {
-                // Identical (template, etag) already emitted this process —
-                // skip the re-dump (the forensic's duplicate-84KB waste).
-                return jsonResult({
-                    unchanged: true,
-                    template_id: templateId,
-                    etag,
-                    note: `[unchanged] layout identical to your previous read (etag ${etag}) — ` +
-                        're-read skipped; pass force:true to re-fetch.',
-                });
-            }
-        }
-        // Record the etag served for this (nested) full read so a later
-        // identical read can be short-circuited. Only nested full reads are
-        // tracked — flat/projected reads have a different downstream shape.
-        if (flat !== true && etag !== undefined) {
-            layoutDedupCache.set(dedupKey, etag);
-        }
-        if (flat !== true) {
-            // Default: nested passthrough — unchanged from pre-G.3, except an
-            // OPTIONAL G-B `max_chars` caps the (potentially large) JSON text
-            // leg. B7 (Glöckle continuation cursor): when the dump is clipped
-            // (by `max_chars` or resumed via `cursor`) it now also emits a
-            // `next_cursor` so an agent can page through the REST of the
-            // subtree instead of being stuck with the first slice. With no
-            // `max_chars` AND no cursor the whole body is returned with no
-            // cursor — byte-identical to the pre-B7 `applyMaxChars(…,
-            // undefined)` no-op.
-            if (max_chars !== undefined || isContinuation) {
-                return windowedFullDump(data, charOffset, max_chars);
-            }
-            return applyMaxChars(jsonResult(data), max_chars);
-        }
-        // flat: true → depth-first walk on the nested layout. Apply
-        // pickFields per element when `fields[]` was passed; echo the
-        // projection so the AI knows the per-item shape it received.
-        //
-        // Several distinct envelope shapes reach this handler — all must
-        // flatten to the same element list. Resolution funnels through
-        // ONE rule (`unwrapToWalkableContainer`) so a single root NODE
-        // (`{type:'layout', children:[...]}`) is never handed to
-        // flattenLayout directly:
-        //
-        //   (A) Theme templates: `data.layout = {query, type:'single-post',
-        //       name:'Post', layout:{type:'layout', children:[...],
-        //       version}}` — the actual node tree lives under the INNER
-        //       `layout` field. That inner value is itself a single root
-        //       NODE (not the index-keyed `{0:{...}}` container the older
-        //       fixtures assumed). Handing the root node to flattenLayout
-        //       made it iterate the node's OWN top-level entries
-        //       (`['type',...]`, `['children',[...]]`, `['version',...]`)
-        //       and emit nothing — `elements:[]` silently (C4 fix,
-        //       2026-06-09; verified on wp-dev5 template bFIb-syj). The
-        //       inner-root-node case is now unwrapped to its `.children`,
-        //       unifying it with the per-page path below.
-        //
-        //       Legacy F-208 shape `{name, layout:{0:{...},1:{...}}}`
-        //       (index-keyed inner container) still works: the inner
-        //       value is NOT a root node, so it passes through to
-        //       flattenLayout unchanged.
-        //
-        //   (B) Per-page templates (Wave-9 F7 fix, 2026-05-29): cold-AI
-        //       #8 reported `elements:[]` for a non-empty per-page
-        //       template. Per-page layouts come from PerPageLayoutEncoder
-        //       which decodes to the BARE root node
-        //       `{type:'layout', children:[{...},{...}]}` — NO outer
-        //       `{name, layout:{...}}` wrapper. Same root-node unwrap
-        //       rule as (A), applied at the top level.
-        //
-        // The unwrap rule (single SSoT): if a value is a single root node
-        // (`type === 'layout'` with an array `children`), iterate its
-        // `.children` array so the walker sees real element nodes and
-        // paths anchor on `/layout/children/0`, `/layout/children/1`, …
-        const dataLayout = data.layout;
-        const isObjectNode = dataLayout !== null &&
-            typeof dataLayout === 'object' &&
-            !Array.isArray(dataLayout);
-        const layoutObj = isObjectNode ? dataLayout : null;
-        const hasInnerLayoutField = layoutObj !== null &&
-            'layout' in layoutObj &&
-            layoutObj.layout !== null &&
-            typeof layoutObj.layout === 'object';
-        // Resolve the candidate container ONE hop from the envelope:
-        // shape (A) descends into the inner `layout`; everything else
-        // starts from `data.layout` directly. Then funnel through the
-        // shared root-node unwrap so shapes (A) and (B) — and any future
-        // single-root-node envelope — collapse identically.
-        const candidate = hasInnerLayoutField ? layoutObj.layout : dataLayout;
-        const layoutRoot = unwrapToWalkableContainer(candidate);
-        // LAYOUT_READ-7: pass the resolved template id so flat-mode `path`s are
-        // fully-qualified (`/templates/<id>/layout/children/0`) — matching the
-        // `path` element_list emits. `rel_path` stays the short `/children/0`.
-        const flatElements = flattenLayout(layoutRoot, templateId);
-        // Non-silent fallback (C4) + F29 calibration: if the walk yields
-        // ZERO elements AND the resolved walk container is an unrecognized
-        // NON-EMPTY shape, surface a warning so it can never pass silently.
-        // A genuinely empty container (an empty array — including a bare
-        // `{type:'layout', children:[]}` root that unwrapped to `[]` — or
-        // an empty object) is a real empty page and must NOT warn.
-        const warning = flatElements.length === 0 && isUnrecognizedNonEmptyLayout(layoutRoot)
-            ? 'layout shape not recognized - flat view may be incomplete'
-            : undefined;
-        const projected = projectFields(flatElements, fields, 
-        // No default-set on layout.flat: keep "all" semantics
-        // unless caller opts-in. The echo helper below mirrors that.
-        []);
-        const echo = projectedFieldsEcho(fields, undefined);
-        // F31 (2026-06-10): align the flat-projection path with F23 — when a
-        // caller-requested field appears on NO element (e.g. `label` on a
-        // YT4 layout), don't echo it in `projected_fields` with no signal.
-        // Compute the projection feedback over the FLAT element rows and
-        // surface `unknown_fields` + `available_fields` + a loud
-        // `projection_warning` (the shared F23 SSoT helper) so the agent can
-        // self-correct on the next call. Default-all callers (no fields[])
-        // get no audit overhead — projectionFeedback returns undefined.
-        // SOURCES_BINDING-29 (parallel site): an EMPTY flat result cannot
-        // observe a field vocabulary, so `projectionFeedback` over zero rows
-        // would report EVERY requested field as unknown against an empty
-        // `available_fields`. Suppress the feedback entirely on a zero-element
-        // flatten — the projection is moot when there is nothing to project.
-        const feedback = flatElements.length > 0
-            ? projectionFeedback(flatElements, fields)
-            : undefined;
-        const projectionNote = projectionWarning(feedback);
-        // 1.0.1 Wave-1.7 F-COLD-3: forward the canonical pointer base
-        // through the flat-projection path too so cold agents iterating
-        // with `flat: true` see the same hint they get on the nested
-        // default payload.
-        return jsonResult({
-            elements: projected,
-            ...(warning !== undefined ? { warning } : {}),
-            ...(feedback !== undefined ? {
-                available_fields: [...feedback.available_fields],
-                unknown_fields: [...feedback.unknown_fields],
-            } : {}),
-            // F31: trim the leading space the table-header helper prepends —
-            // here it rides in a JSON field, not a header string. Emitted
-            // ONLY when there's actually an unknown field to flag.
-            ...(projectionNote !== '' ? { projection_warning: projectionNote.trimStart() } : {}),
-            ...(typeof data.etag === 'string' ? { etag: data.etag } : {}),
-            ...(typeof data.layout_root_pointer === 'string'
-                ? { layout_root_pointer: data.layout_root_pointer }
-                : {}),
-            ...(typeof data.pointer_hint === 'string'
-                ? { pointer_hint: data.pointer_hint }
-                : {}),
-            ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
-        });
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id },
-            hint: 'Verify the template_id exists via yootheme_builder_pages_list. ' +
-                'IDs are case-sensitive.',
-        });
-    }
-}
-// ─── page_get_schema ────────────────────────────────────────────────
-export async function handlePageGetSchema(client, { template_id, post_id, url, fields, max_chars }) {
-    try {
-        // G-A: resolve the effective template_id from template_id | post_id | url.
-        const effective = await resolveEffectiveTemplateId(client, { template_id, post_id, url });
-        if ('error' in effective) {
-            return effective.error;
-        }
-        const templateId = effective.templateId;
-        const data = await client.get(`/pages/${encodeTemplateId(templateId)}/schema`);
-        const rawNodes = Array.isArray(data.nodes) ? data.nodes : [];
-        const rows = buildSchemaRows(rawNodes.filter((x) => x !== null && typeof x === 'object'));
-        // G-B (Glöckle 2026-06-26, P2): `fields[]` projection — DEFAULT_FIELDS_SCHEMA
-        // existed but was never wired. Mirror element_list: project both legs,
-        // echo `projected_fields`, surface the F23 unknown-field feedback.
-        const items = projectFields(rows, fields, DEFAULT_FIELDS_SCHEMA);
-        const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_SCHEMA);
-        const feedback = projectionFeedback(rows, fields);
-        const unknownNote = projectionWarning(feedback);
-        const hasNarrowProjection = Array.isArray(fields) && fields.length > 0;
-        // Templates routinely exceed 21 nodes (a typical home page has
-        // 30–150 elements). Force compact level so the LLM never gets
-        // truncated text — toolkit's resolveDetailLevel honours the
-        // explicit override. With a narrow `fields[]` projection, render the
-        // projected rows from caller-chosen columns (mirrors element_list).
-        //
-        // TODO(toolkit-upstream): contribute a `compactWhen: (count) => boolean`
-        // field to @getimo/mcp-toolkit's AutoFormatOptions so this
-        // can be expressed declaratively on the config object instead
-        // of via the third positional argument. Tracked as Round-1.5
-        // follow-up (I2).
-        const toolkitResult = hasNarrowProjection
-            ? tableResult(items, {
-                columns: columnsFromFields([...fields]),
-                header: (count) => `${String(count)} nodes in template "${templateId}"${unknownNote}`,
-                footer: 'Use yootheme_builder_element_get <path> for full element data.',
-            }, 'compact')
-            : tableResult(rows, {
-                columns: [...SCHEMA_TABLE_COLUMNS],
-                compactColumns: [...SCHEMA_COMPACT_COLUMNS],
-                header: (count) => `${String(count)} nodes in template "${templateId}"`,
-                footer: 'Use yootheme_builder_element_get <path> for full element data.',
-            }, 'compact');
-        return structuredResult(applyMaxChars(toolkitResult, max_chars), {
-            items,
-            total: items.length,
-            template_id: templateId,
-            ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
-            ...(feedback !== undefined ? {
-                available_fields: [...feedback.available_fields],
-                unknown_fields: [...feedback.unknown_fields],
-                ...(unknownNote.trim() !== '' ? { projection_warning: unknownNote.trim() } : {}),
-            } : {}),
-        });
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id },
-            hint: 'Verify the template_id exists via yootheme_builder_pages_list.',
-        });
-    }
-}
-// ─── get_etag ───────────────────────────────────────────────────────
-export async function handleGetEtag(client) {
-    try {
-        const data = await client.get('/etag');
-        const toolkitResult = detailResult(buildEtagDetail({
-            etag: data.etag,
-            generated_at: data.generated_at,
-        }));
-        return structuredResult(toolkitResult, {
-            etag: data.etag,
-            ...(typeof data.generated_at === 'string'
-                ? { generated_at: data.generated_at }
-                : {}),
-        });
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: {},
-            hint: 'Run yootheme_builder_diagnose to verify auth.',
-        });
-    }
-}
-// ─── template_summary (T9 — Audit-v3 B.5 token-efficient overview) ────
-/**
- * T9: a one-call structured overview of a template — element counts by
- * type, binding count, max nesting depth, and named landmarks. Lets the
- * agent grasp a 96-node template for ~1 kB instead of pulling the full
- * element_list dump (20 kB+).
- */
-export async function handleTemplateSummary(client, { template_id }) {
-    try {
-        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/summary`);
-        // F-AUDIT-2 (2026-05-26): template_summary now declares
-        // TEMPLATE_SUMMARY_OUTPUT_SCHEMA. The SDK requires
-        // `structuredContent` when an outputSchema is present, otherwise
-        // it raises `-32602 Output validation error`. Wrap the raw body
-        // with `structuredResult` so the text leg (LLM-readable JSON)
-        // stays unchanged AND the structuredContent leg validates.
-        //
-        // Task #46 Friction-3 (2026-05-29): PHP's `json_encode([])` emits
-        // `[]` (array) — not `{}` (object). The REST handler emits
-        // `counts_by_type: []` for empty templates, but the outputSchema
-        // declares `z.record(z.string(), z.number())` which requires an
-        // object. The mismatch surfaces as `-32602 counts_by_type
-        // expected record, received array`, swallowing the entire response
-        // for any empty / freshly-created template. Normalize array→object
-        // here so the schema validates and the agent sees the (valid,
-        // empty) summary. Same defensive shape applies to any future
-        // map-typed REST field that might come back empty.
-        const normalized = {
-            ...data,
-        };
-        if (Array.isArray(normalized.counts_by_type)) {
-            normalized.counts_by_type = {};
-        }
-        const toolkitResult = jsonResult(normalized);
-        return structuredResult({ content: toolkitResult.content }, normalized);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id },
-            hint: 'Verify the template_id exists via yootheme_builder_pages_list.',
-        });
-    }
-}
-// ─── render_preview (F5 + N5 — authenticated post-write render check) ──
-/**
- * F5 + N5 (Glöckle HANDOFF-4/5): the authenticated post-write render
- * HEALTHCHECK. Resolves the EFFECTIVE template_id from `template_id` OR `url`
- * (the SAME `resolveEffectiveTemplateId` precedence page_get_layout uses — a
- * pasted public URL is reverse-resolved via GET /pages/resolve first), then
- * GETs `/pages/{id}/render-preview` which runs the in-process read-only Builder
- * render server-side over the already-authenticated Bearer channel — answering
- * "renders / N items / blank?" where an external cURL 401s behind QA Basic-Auth.
- *
- * Returns the strict RENDER_PREVIEW_OUTPUT_SCHEMA shape: `{rendered, item_count,
- * empty, error?, cache_purge_hint, template_id}`. A render that resolved to zero
- * items, or that threw inside the Builder pipeline (the swallowed YOOtheme
- * render error surfaced as `error`), is a SUCCESS — not a tool error.
- */
-export async function handleRenderPreview(client, { template_id, post_id, url, expect }) {
-    try {
-        // WAVE-1 follow-up (a): render_preview now accepts `post_id` too, the SAME
-        // three-mode addressing page_get_layout uses — template_id wins, else a
-        // bare numeric post/article id, else a `url` reverse-resolved via
-        // /pages/resolve. (Cross-file: the RENDER_PREVIEW input schema in
-        // pages/builders.ts must also declare `post_id` + the native catalog must
-        // carry it — flagged for the coordinator regen.)
-        const effective = await resolveEffectiveTemplateId(client, { template_id, post_id, url });
-        if ('error' in effective) {
-            return effective.error;
-        }
-        const templateId = effective.templateId;
-        // Glöckle HANDOFF-6 #4: an `expect` substring is passed to the render
-        // endpoint as a query param (the server greps the rendered HTML and adds
-        // {matched, snippet}). A blank value is treated as "no check".
-        const wantMatch = typeof expect === 'string' && expect !== '';
-        const query = wantMatch ? `?${new URLSearchParams({ expect }).toString()}` : '';
-        const data = await client.get(`/pages/${encodeTemplateId(templateId)}/render-preview${query}`);
-        // Normalize the REST body into the strict output shape. Defensive
-        // coercion keeps a malformed/partial host payload from tripping the
-        // strict outputSchema (-32602) — the structured leg MUST validate.
-        const payload = {
-            template_id: typeof data.template_id === 'string' ? data.template_id : templateId,
-            rendered: data.rendered === true,
-            item_count: typeof data.item_count === 'number' && Number.isFinite(data.item_count)
-                ? Math.max(0, Math.trunc(data.item_count))
-                : 0,
-            empty: data.empty !== false,
-            cache_purge_hint: typeof data.cache_purge_hint === 'string' ? data.cache_purge_hint : '',
-            ...(typeof data.error === 'string' ? { error: data.error } : {}),
-            // The {matched, snippet} pair is surfaced ONLY when `expect` was
-            // requested. `matched` coerces to a strict boolean; `snippet` is a
-            // string when present, else null (a miss / a render that threw).
-            ...(wantMatch
-                ? {
-                    matched: data.matched === true,
-                    snippet: typeof data.snippet === 'string' ? data.snippet : null,
-                }
-                : {}),
-        };
-        return structuredResult(detailResult(buildRenderPreviewDetail(payload)), {
-            rendered: payload.rendered,
-            item_count: payload.item_count,
-            empty: payload.empty,
-            cache_purge_hint: payload.cache_purge_hint,
-            template_id: payload.template_id,
-            ...(payload.error !== undefined ? { error: payload.error } : {}),
-            ...(payload.matched !== undefined ? { matched: payload.matched } : {}),
-            ...(wantMatch ? { snippet: payload.snippet ?? null } : {}),
-        });
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, post_id, url, expect },
-            hint: 'Verify the template_id exists via yootheme_builder_pages_list ' +
-                '(or that post_id / the url resolves). Run yootheme_builder_diagnose to check auth.',
-        });
-    }
-}
-//# sourceMappingURL=handlers-read.js.map