@wootsup/yt-builder-mcp 1.1.5 → 1.1.7

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

@@ -0,0 +1,203 @@
+/**
+ * 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 { flattenLayout } from '../layout-flatten.js';
+import { PAGES_COMPACT_COLUMNS, PAGES_TABLE_COLUMNS, SCHEMA_COMPACT_COLUMNS, SCHEMA_TABLE_COLUMNS, buildEtagDetail, buildSchemaRows, mapPageRow, } from '../format/pages-format.js';
+import { DEFAULT_FIELDS_PAGES_LIST, projectFields, projectedFieldsEcho, projectionFeedback, } from '../sparse-fields.js';
+import { errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
+// ─── pages_list ─────────────────────────────────────────────────────
+export async function handlePagesList(client, { fields }) {
+    try {
+        const data = await client.get('/pages');
+        const rawPages = Array.isArray(data.pages) ? data.pages : [];
+        const mapped = rawPages
+            .filter((x) => x !== null && typeof x === 'object')
+            .map(mapPageRow);
+        // Project AFTER mapping — keeps stable key names and lets the
+        // toolkit's tableResult format the raw, full-shape rows for the
+        // LLM text leg while the structuredContent leg carries the
+        // projected per-item slice.
+        const items = projectFields(mapped, fields, DEFAULT_FIELDS_PAGES_LIST);
+        const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_PAGES_LIST);
+        const feedback = projectionFeedback(mapped, fields);
+        const unknownNote = feedback !== undefined && feedback.unknown_fields.length > 0
+            ? ` (unknown fields ignored: ${feedback.unknown_fields.join(', ')}; available: ${feedback.available_fields.join(', ')})`
+            : '';
+        const toolkitResult = tableResult(mapped, {
+            columns: [...PAGES_TABLE_COLUMNS],
+            compactColumns: [...PAGES_COMPACT_COLUMNS],
+            header: (count) => `${String(count)} pages${unknownNote}`,
+            footer: 'Use yootheme_builder_page_get_schema <id> to inspect.',
+        });
+        return structuredResult(toolkitResult, {
+            items,
+            total: items.length,
+            ...(typeof data.etag === 'string' ? { etag: data.etag } : {}),
+            ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
+            ...(feedback !== undefined ? {
+                available_fields: [...feedback.available_fields],
+                unknown_fields: [...feedback.unknown_fields],
+            } : {}),
+        });
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: {},
+            hint: 'Run yootheme_builder_diagnose to verify connectivity and auth.',
+        });
+    }
+}
+// ─── page_get_layout ────────────────────────────────────────────────
+export async function handlePageGetLayout(client, { template_id, flat, fields }) {
+    try {
+        const data = await client.get(`/pages/${encodeURIComponent(template_id)}/layout`);
+        if (flat !== true) {
+            // Default: nested passthrough — unchanged from pre-G.3.
+            return jsonResult(data);
+        }
+        // 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.
+        //
+        // F-208 (Audit 2026-05-26): the REST envelope nests the actual
+        // node tree as `data.layout.layout` — `data.layout` is the
+        // WHOLE template object (`{name, layout: {…children…}, …}`),
+        // so walking `data.layout` directly produced double-prefixed
+        // paths (`/layout/layout/children/0`). Detect the template
+        // envelope by presence of an inner `layout` field and descend
+        // one extra hop. Back-compat: when `data.layout` is already
+        // the node tree (no inner `layout` key), pass it through.
+        const layoutRoot = data.layout !== null &&
+            typeof data.layout === 'object' &&
+            !Array.isArray(data.layout) &&
+            'layout' in data.layout &&
+            data.layout.layout !== null &&
+            typeof data.layout.layout === 'object'
+            ? data.layout.layout
+            : data.layout;
+        const flatElements = flattenLayout(layoutRoot);
+        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);
+        // 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,
+            ...(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 }) {
+    try {
+        const data = await client.get(`/pages/${encodeURIComponent(template_id)}/schema`);
+        const rawNodes = Array.isArray(data.nodes) ? data.nodes : [];
+        const items = buildSchemaRows(rawNodes.filter((x) => x !== null && typeof x === 'object'));
+        // 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.
+        //
+        // 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 = tableResult(items, {
+            columns: [...SCHEMA_TABLE_COLUMNS],
+            compactColumns: [...SCHEMA_COMPACT_COLUMNS],
+            header: (count) => `${String(count)} nodes in template "${template_id}"`,
+            footer: 'Use yootheme_builder_element_get <path> for full element data.',
+        }, 'compact');
+        return structuredResult(toolkitResult, {
+            items,
+            total: items.length,
+            template_id,
+        });
+    }
+    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/${encodeURIComponent(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.
+        const toolkitResult = jsonResult(data);
+        return structuredResult({ content: toolkitResult.content }, data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id },
+            hint: 'Verify the template_id exists via yootheme_builder_pages_list.',
+        });
+    }
+}
+//# sourceMappingURL=handlers-read.js.map

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

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

package/dist/tools/pages/handlers-write.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Page-tool WRITE handlers — `page_save`, `page_publish`. Both implement
+ * the 3-phase progress contract (PHASE_SEND → PHASE_SERVER → PHASE_CONFIRM).
+ * PHASE_SERVER is emitted BEFORE the await so the synthetic intermediate
+ * fires even when the REST call ultimately errors — the dispatch IS the
+ * boundary, not the response.
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1).
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../../client.js';
+import { type HandlerExtra, type ToolResult } from '../tool-builder.js';
+interface SavePublishInput {
+    template_id: string;
+    etag?: string;
+}
+export declare function handlePageSave(client: RestClient, { template_id, etag }: SavePublishInput, extra?: HandlerExtra): Promise<ToolResult>;
+export declare function handlePagePublish(client: RestClient, { template_id, etag }: SavePublishInput, extra?: HandlerExtra): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=handlers-write.d.ts.map

package/dist/tools/pages/handlers-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-write.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/handlers-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAIH,KAAK,YAAY,EACjB,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,UAAU,gBAAgB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,wBAAsB,cAAc,CAChC,MAAM,EAAE,UAAU,EAClB,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,gBAAgB,EACvC,KAAK,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,UAAU,CAAC,CAoBrB;AAID,wBAAsB,iBAAiB,CACnC,MAAM,EAAE,UAAU,EAClB,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,gBAAgB,EACvC,KAAK,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,UAAU,CAAC,CAoBrB"}

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

@@ -0,0 +1,52 @@
+/**
+ * Page-tool WRITE handlers — `page_save`, `page_publish`. Both implement
+ * the 3-phase progress contract (PHASE_SEND → PHASE_SERVER → PHASE_CONFIRM).
+ * PHASE_SERVER is emitted BEFORE the await so the synthetic intermediate
+ * fires even when the REST call ultimately errors — the dispatch IS the
+ * boundary, not the response.
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1).
+ *
+ * @license MIT
+ */
+import { PHASE_CONFIRM, PHASE_SEND, PHASE_SERVER } from '../progress-phases.js';
+import { createProgressReporter, errorResult, jsonResult, } from '../tool-builder.js';
+// ─── page_save ──────────────────────────────────────────────────────
+export async function handlePageSave(client, { template_id, etag }, extra) {
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 3, PHASE_SEND);
+    await progress?.report(1, 3, PHASE_SERVER);
+    try {
+        const data = await client.post(`/pages/${encodeURIComponent(template_id)}/save`, { etag });
+        await progress?.report(2, 3, PHASE_CONFIRM);
+        return jsonResult(data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, etag },
+            hint: 'On 412 (precondition failed) refresh via yootheme_builder_get_etag ' +
+                'and retry — someone else edited the page.',
+        });
+    }
+}
+// ─── page_publish ───────────────────────────────────────────────────
+export async function handlePagePublish(client, { template_id, etag }, extra) {
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 3, PHASE_SEND);
+    await progress?.report(1, 3, PHASE_SERVER);
+    try {
+        const data = await client.post(`/pages/${encodeURIComponent(template_id)}/publish`, { etag });
+        await progress?.report(2, 3, PHASE_CONFIRM);
+        return jsonResult(data);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, etag },
+            hint: 'On 412 (precondition failed) refresh via yootheme_builder_get_etag ' +
+                'and retry.',
+        });
+    }
+}
+//# sourceMappingURL=handlers-write.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-write.js","sourceRoot":"","sources":["../../../src/tools/pages/handlers-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EACH,sBAAsB,EACtB,WAAW,EACX,UAAU,GAGb,MAAM,oBAAoB,CAAC;AAO5B,uEAAuE;AAEvE,MAAM,CAAC,KAAK,UAAU,cAAc,CAChC,MAAkB,EAClB,EAAE,WAAW,EAAE,IAAI,EAAoB,EACvC,KAAoB;IAEpB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IACzC,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,kBAAkB,CAAC,WAAW,CAAC,OAAO,EAChD,EAAE,IAAI,EAAE,CACX,CAAC;QACF,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,aAAa,CAAC,CAAC;QAC5C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;YAC9B,IAAI,EACA,qEAAqE;gBACrE,2CAA2C;SAClD,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED,uEAAuE;AAEvE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACnC,MAAkB,EAClB,EAAE,WAAW,EAAE,IAAI,EAAoB,EACvC,KAAoB;IAEpB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IACzC,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,kBAAkB,CAAC,WAAW,CAAC,UAAU,EACnD,EAAE,IAAI,EAAE,CACX,CAAC;QACF,MAAM,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,aAAa,CAAC,CAAC;QAC5C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;YAC9B,IAAI,EACA,qEAAqE;gBACrE,YAAY;SACnB,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}

package/dist/tools/pages/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Page-tool barrel — public entry-point for the 6 page-level tools:
+ *
+ *   yootheme_builder_pages_list        → list templates (tableResult + structuredContent)
+ *   yootheme_builder_page_get_layout   → full layout tree (jsonResult)
+ *   yootheme_builder_page_get_schema   → flat schema (tableResult compact)
+ *   yootheme_builder_page_save         → re-run save-transforms + persist
+ *   yootheme_builder_page_publish      → publish
+ *   yootheme_builder_get_etag          → top-level state ETag (detailResult)
+ *
+ * Round-2 R2-A2-CRIT1 — split out of the original `src/tools/pages.ts`.
+ *
+ * @license MIT
+ */
+export { buildPagesTools } from './builders.js';
+export { ETAG_OUTPUT_SCHEMA, PAGES_LIST_OUTPUT_SCHEMA, SCHEMA_OUTPUT_SCHEMA, TEMPLATE_SUMMARY_OUTPUT_SCHEMA, } from './schemas.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/pages/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,8BAA8B,GACjC,MAAM,cAAc,CAAC"}

package/dist/tools/pages/index.js

@@ -0,0 +1,17 @@
+/**
+ * Page-tool barrel — public entry-point for the 6 page-level tools:
+ *
+ *   yootheme_builder_pages_list        → list templates (tableResult + structuredContent)
+ *   yootheme_builder_page_get_layout   → full layout tree (jsonResult)
+ *   yootheme_builder_page_get_schema   → flat schema (tableResult compact)
+ *   yootheme_builder_page_save         → re-run save-transforms + persist
+ *   yootheme_builder_page_publish      → publish
+ *   yootheme_builder_get_etag          → top-level state ETag (detailResult)
+ *
+ * Round-2 R2-A2-CRIT1 — split out of the original `src/tools/pages.ts`.
+ *
+ * @license MIT
+ */
+export { buildPagesTools } from './builders.js';
+export { ETAG_OUTPUT_SCHEMA, PAGES_LIST_OUTPUT_SCHEMA, SCHEMA_OUTPUT_SCHEMA, TEMPLATE_SUMMARY_OUTPUT_SCHEMA, } from './schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/pages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/pages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACH,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,8BAA8B,GACjC,MAAM,cAAc,CAAC"}

package/dist/tools/pages/schemas.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Page-tool output-schemas (Wave G.2 §4 structuredContent contracts).
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) so the
+ * handler files stay focused on logic.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+export declare const PAGES_LIST_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total: z.ZodNumber;
+    etag: 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 SCHEMA_OUTPUT_SCHEMA: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        rel_path: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        element_type: z.ZodString;
+        label: z.ZodString;
+        has_binding: z.ZodBoolean;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    template_id: z.ZodString;
+}, z.core.$strip>;
+export declare const ETAG_OUTPUT_SCHEMA: z.ZodObject<{
+    etag: z.ZodString;
+    generated_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const TEMPLATE_SUMMARY_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    counts_by_type: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    bound_count: z.ZodNumber;
+    max_depth: z.ZodNumber;
+    total: z.ZodNumber;
+    named_sections: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    etag: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/tools/pages/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,wBAAwB;;;;;;;iBA8BnC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAiB/B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AAWH,eAAO,MAAM,8BAA8B;;;;;;;;;;;iBAazC,CAAC"}

package/dist/tools/pages/schemas.js

@@ -0,0 +1,82 @@
+/**
+ * Page-tool output-schemas (Wave G.2 §4 structuredContent contracts).
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) so the
+ * handler files stay focused on logic.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+export const PAGES_LIST_OUTPUT_SCHEMA = z.object({
+    // F-Frontend-URL (2026-05-25): each row carries `frontend_url`,
+    // `frontend_url_template`, `frontend_url_description` so an MCP-agent
+    // can answer "What is the URL of my <type> template?" without a
+    // follow-up REST call or operator input. Server-side resolvers
+    // (WordPress: get_permalink/get_term_link/get_author_posts_url; Joomla:
+    // RouteHelper::getArticleRoute/getCategoryRoute/getTagRoute) emit one
+    // of two shapes per row:
+    //   - `frontend_url: <permalink>` + `frontend_url_template: null`
+    //     when a canonical public URL exists (latest post / first category
+    //     / first author etc.).
+    //   - `frontend_url: null` + `frontend_url_template: <pattern>` when
+    //     the URL needs a runtime parameter (search, 404-test) or when no
+    //     public content of the matching type exists yet.
+    // `frontend_url_description` is a short human hint ("Append any non-
+    // existent path to test." / "Latest published post — rendered with
+    // this template.") so the agent can render an instruction to the
+    // end-user. All three keys are kept on the row-record (not an extra
+    // schema object) so per-item sparse-field projection works.
+    items: z.array(z.record(z.string(), z.unknown())),
+    total: z.number(),
+    etag: z.string().optional(),
+    projected_fields: z.array(z.string()).optional(),
+    // F-004 fix (2026-05-25 exhaustive audit): projection-feedback —
+    // emitted ONLY when the caller passed `fields[]`. `available_fields`
+    // is the discovered top-level field vocabulary; `unknown_fields` is
+    // the subset of requested fields that did NOT appear in any item
+    // (previously: items came back as `[{}, {}, …]` silently).
+    available_fields: z.array(z.string()).optional(),
+    unknown_fields: z.array(z.string()).optional(),
+});
+export const SCHEMA_OUTPUT_SCHEMA = z.object({
+    // F-006 (2026-05-26): `rel_path` is the agent-preferred path form
+    // (matches `element_list` + `page_get_layout` emit). `path` (the
+    // fully-qualified `/templates/<id>/layout/...` pointer) stays on the
+    // row for back-compat but is optional so callers reading the schema
+    // know `rel_path` is the canonical projection column.
+    items: z.array(z.object({
+        rel_path: z.string(),
+        path: z.string().optional(),
+        element_type: z.string(),
+        label: z.string(),
+        has_binding: z.boolean(),
+    })),
+    total: z.number(),
+    template_id: z.string(),
+});
+export const ETAG_OUTPUT_SCHEMA = z.object({
+    etag: z.string(),
+    generated_at: z.string().optional(),
+});
+// F-AUDIT-2 (2026-05-26): template_summary outputSchema. The handler
+// passes the REST `/pages/{id}/summary` body through verbatim via
+// `jsonResult(data)`. Live shape verified against the WP+Joomla dev
+// hosts: `template_id`, `counts_by_type` (open-ended map element-type
+// → count), `bound_count`, `max_depth`, `total`, `named_sections` (each
+// `{path, name}`), and the `etag` string. NOTE: `_meta` is merged at
+// the RESULT-LEVEL by `withSiteMeta`, NEVER into `structuredContent`
+// (see results.ts W12-R2 commentary) — this schema therefore validates
+// only the inner template-summary shape.
+export const TEMPLATE_SUMMARY_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    counts_by_type: z.record(z.string(), z.number().int().nonnegative()),
+    bound_count: z.number().int().nonnegative(),
+    max_depth: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    named_sections: z.array(z.object({
+        path: z.string(),
+        name: z.string(),
+    })),
+    etag: z.string(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/tools/pages/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/tools/pages/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,gEAAgE;IAChE,sEAAsE;IACtE,gEAAgE;IAChE,+DAA+D;IAC/D,wEAAwE;IACxE,sEAAsE;IACtE,yBAAyB;IACzB,kEAAkE;IAClE,uEAAuE;IACvE,4BAA4B;IAC5B,qEAAqE;IACrE,sEAAsE;IACtE,sDAAsD;IACtD,qEAAqE;IACrE,mEAAmE;IACnE,iEAAiE;IACjE,oEAAoE;IACpE,4DAA4D;IAC5D,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACjD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAChD,iEAAiE;IACjE,qEAAqE;IACrE,oEAAoE;IACpE,iEAAiE;IACjE,2DAA2D;IAC3D,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAChD,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,kEAAkE;IAClE,iEAAiE;IACjE,qEAAqE;IACrE,oEAAoE;IACpE,sDAAsD;IACtD,KAAK,EAAE,CAAC,CAAC,KAAK,CACV,CAAC,CAAC,MAAM,CAAC;QACL,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC3B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;KAC3B,CAAC,CACL;IACD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CAC1B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAEH,qEAAqE;AACrE,kEAAkE;AAClE,oEAAoE;AACpE,sEAAsE;AACtE,wEAAwE;AACxE,qEAAqE;AACrE,qEAAqE;AACrE,uEAAuE;AACvE,yCAAyC;AACzC,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IACpE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC3C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACzC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,cAAc,EAAE,CAAC,CAAC,KAAK,CACnB,CAAC,CAAC,MAAM,CAAC;QACL,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;KACnB,CAAC,CACL;IACD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC"}

package/dist/tools/pages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `src/tools/pages.ts`.
+ *
+ * The original 358-LoC module was split into `src/tools/pages/`
+ * (5 files, each ≤ 200 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT1 audit fix). This shim preserves the public import path
+ * (`from '../../src/tools/pages.js'`) so all existing test imports
+ * and `tools/index.ts` keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './pages/index.js';
+//# sourceMappingURL=pages.d.ts.map

package/dist/tools/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/tools/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/tools/pages.js

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `src/tools/pages.ts`.
+ *
+ * The original 358-LoC module was split into `src/tools/pages/`
+ * (5 files, each ≤ 200 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT1 audit fix). This shim preserves the public import path
+ * (`from '../../src/tools/pages.js'`) so all existing test imports
+ * and `tools/index.ts` keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './pages/index.js';
+//# sourceMappingURL=pages.js.map

package/dist/tools/pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.js","sourceRoot":"","sources":["../../src/tools/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/tools/pool-resolve-helper.d.ts

@@ -0,0 +1,83 @@
+/**
+ * W6.3 — shared helper for the per-handler `pool.resolve(site_id)`
+ * pattern.
+ *
+ * Every tool handler does the same dance:
+ *   1. Extract `site_id` from args (optional, undefined → default site).
+ *   2. Call `pool.resolve(site_id)`.
+ *   3. Translate `NoDefaultSiteError` / `UnknownSiteError` into a
+ *      structured `errorResult` so the agent can self-recover.
+ *   4. Hand back `{client, site}` for downstream use.
+ *
+ * Centralising the dance keeps the 24 handler bodies short and ensures
+ * the error wording stays consistent across the tool surface.
+ *
+ * @license MIT
+ */
+import { type ClientPool, type PoolResolution } from '../sites/client-pool.js';
+import type { ResolvedSite } from '../sites/registry.js';
+import type { RestClient } from '../client.js';
+import { type ToolResult } from './tool-builder.js';
+/**
+ * Discriminated union returned by {@link resolveSiteOrError}: callers
+ * check the `ok` boolean before destructuring. When `ok === false`,
+ * the `error` field is a fully-formed `ToolResult` ready to be
+ * returned from the handler verbatim (no further wrapping needed).
+ *
+ * The dual-channel shape lets handlers keep their flat top-level
+ * control flow:
+ *
+ *   const r = await resolveSiteOrError(pool, args.site_id);
+ *   if (!r.ok) return r.error;
+ *   const { client, site } = r;
+ *   // ... existing logic ...
+ *   return withSiteMeta(result, site);
+ */
+export type SiteResolution = {
+    readonly ok: true;
+    readonly client: PoolResolution['client'];
+    readonly site: PoolResolution['site'];
+} | {
+    readonly ok: false;
+    readonly error: ToolResult;
+};
+/**
+ * Resolve a site_id through the pool, translating the W4 typed errors
+ * into structured `ToolResult` envelopes. Non-typed errors (genuine
+ * fetch failures during the platform probe, secret-resolver crashes,
+ * etc.) re-throw so the handler's outer try/catch can shape them with
+ * domain-specific hints.
+ */
+export declare function resolveSiteOrError(pool: ClientPool, siteId: string | undefined): Promise<SiteResolution>;
+/**
+ * W12-R2A (A4-F3 / A5-S2) — resolve a site + execute a handler-body with
+ * a 1-shot 401 retry.
+ *
+ * Bearer-rotation use case: a site's bearer is revoked / rotated /
+ * expired AFTER the pool cached a {@link RestClient} for it. The next
+ * call returns HTTP 401. Without retry the agent has to be told
+ * "restart your client". With retry we drop the cached client (so the
+ * next `pool.resolve` re-runs `secretResolver.resolve`), then call the
+ * handler-body again exactly once. If the second attempt also returns
+ * 401, we surface a structured `bearer_invalid` error with an
+ * actionable hint pointing at `sites_test` / sites.json.
+ *
+ * Scope: deliberately ONE retry. A second 401 means the bearer is
+ * genuinely revoked at the source — looping forever wastes tokens and
+ * masks the real problem.
+ *
+ * The wrapper handles {@link NoDefaultSiteError} / {@link
+ * UnknownSiteError} via the same `resolveSiteOrError` envelope so
+ * call-sites don't have to duplicate the structured-error wording.
+ * Non-401 thrown errors propagate to the handler's outer try/catch
+ * (or the SDK boundary) untouched — only HTTP 401 triggers the retry
+ * / structured-error path.
+ *
+ * Usage (post-migration):
+ *
+ *   handler: async ({ site_id, ...rest }) =>
+ *     withSiteRetry(pool, site_id, async (client, site) =>
+ *       withSiteMeta(await handleX(makeDeps(client), rest), site)),
+ */
+export declare function withSiteRetry(pool: ClientPool, siteId: string | undefined, fn: (client: RestClient, site: ResolvedSite) => Promise<ToolResult>): Promise<ToolResult>;
+//# sourceMappingURL=pool-resolve-helper.d.ts.map

package/dist/tools/pool-resolve-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-resolve-helper.d.ts","sourceRoot":"","sources":["../../src/tools/pool-resolve-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACH,KAAK,UAAU,EAEf,KAAK,cAAc,EAEtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;CAAE,GACvG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,cAAc,CAAC,CAqDzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,aAAa,CAC/B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,UAAU,CAAC,GACpE,OAAO,CAAC,UAAU,CAAC,CA8CrB"}