@wootsup/yt-builder-mcp 1.0.1 → 1.1.0

package/dist/tools/health.js

@@ -0,0 +1,220 @@
+/**
+ * Health & diagnostics tools.
+ *
+ *   yootheme_builder_health
+ *      → GET /health (unauthenticated). Verifies the plugin is
+ *        installed and reachable. Returns plugin/YT/WP/PHP versions
+ *        + available endpoints.
+ *
+ *   yootheme_builder_diagnose
+ *      → Aggregates health + a Bearer-auth probe so the agent can
+ *        distinguish "plugin missing" from "wrong key".
+ *
+ * Both tools emit `detailResult` (Wave G.2) so hosts that support
+ * structured content render a Detail-Card; the LLM still reads the text
+ * leg from `content[0].text`.
+ *
+ * @license MIT
+ */
+import { detailResult, statsResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { RestError } from '../errors.js';
+import { buildDiagnoseDetail, buildHealthStats, } from './format/health-format.js';
+import { SITE_ID_SCHEMA } from './shared-schemas.js';
+import { resolveSiteOrError } from './pool-resolve-helper.js';
+import { defineTool, errorResult, jsonResult, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
+// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+const HEALTH_OUTPUT_SCHEMA = z.object({
+    plugin_version: z.string(),
+    // Cross-platform note (Wave 7): the anonymous health payload only carries
+    // {plugin_version, status, yootheme_loaded}; the rest is disclosed ONLY
+    // with a valid Bearer (server-side fingerprint-reduction). On Joomla the
+    // augmented payload uses `cms`/`cms_version` and emits NEITHER `wp_version`
+    // NOR `yootheme_version`. All platform-/tier-variable fields are therefore
+    // optional so the same MCP tool validates against WP and Joomla, anon and
+    // authenticated.
+    yootheme_version: z.string().nullable().optional(),
+    wp_version: z.string().nullable().optional(),
+    cms: z.string().optional(),
+    cms_version: z.string().optional(),
+    php_version: z.string().optional(),
+    storage_type: z.string().optional(),
+    storage_target: z.string().optional(),
+    yootheme_loaded: z.boolean(),
+    available_endpoints: z.array(z.string()).optional(),
+    // 1.0.1 — surface canonical WP URLs so an agent can deep-link the
+    // customer to the live site without a separate REST round-trip.
+    // Both fields are optional in the schema for back-compat with older
+    // 1.0.0 PHP servers that don't yet emit them.
+    site_url: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Canonical WordPress install URL including any subpath ' +
+        '(e.g. `https://example.com/wordpress`). Authenticated payload only.'),
+    home_url: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Front-end home URL — use this to deep-link the user to the live ' +
+        'site they edited.'),
+});
+const DIAGNOSE_OUTPUT_SCHEMA = z.object({
+    plugin_reachable: z.boolean(),
+    plugin_version: z.string().optional(),
+    yootheme_loaded: z.boolean().optional(),
+    yootheme_version: z.string().nullable().optional(),
+    endpoint_count: z.number().optional(),
+    plugin_error: z.string().optional(),
+    bearer_valid: z.boolean().optional(),
+    bearer_error: z.string().optional(),
+    summary: z.string().optional(),
+    // 1.0.1 — mirror the health fields for parity. Diagnose calls /health
+    // internally so it has the values; surfacing them avoids forcing the
+    // agent to call both tools to get URL info + bearer status.
+    site_url: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Canonical WordPress install URL including any subpath ' +
+        '(e.g. `https://example.com/wordpress`). Mirrored from /health so an ' +
+        'agent gets URL info + bearer status in one call.'),
+    home_url: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Front-end home URL — use this to deep-link the user to the live ' +
+        'site they edited.'),
+});
+export function buildHealthTools(pool) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_health',
+            description: 'Check plugin installed/reachable. Returns plugin version, YT Pro version, REST ' +
+                'endpoints. Authenticated payload adds site_url + home_url for deep-linking. ' +
+                'See yootheme_builder_diagnose for Bearer-validity + connectivity summary. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+            },
+            outputSchema: HEALTH_OUTPUT_SCHEMA,
+            annotations: readOnly('Health Check'),
+            handler: async ({ site_id }) => {
+                const r = await resolveSiteOrError(pool, site_id);
+                if (!r.ok)
+                    return r.error;
+                const { client: siteClient, site } = r;
+                try {
+                    const data = await siteClient.get('/health');
+                    // Round-1 audit I1 fix: spec §3.2 row 1 calls for
+                    // `statsResult` (flat metrics). Earlier shipped
+                    // `detailResult` — that's a Detail-Card variant, not
+                    // the stats-display the spec asked for. The flat
+                    // shape is built by `buildHealthStats`.
+                    const toolkitResult = statsResult(buildHealthStats(data));
+                    // Only surface fields the server actually returned — the
+                    // anonymous tier and Joomla omit different subsets, and the
+                    // output schema now marks all platform-/tier-variable fields
+                    // optional (Wave 7 cross-platform parity).
+                    return withSiteMeta(structuredResult(toolkitResult, {
+                        plugin_version: data.plugin_version,
+                        yootheme_loaded: data.yootheme_loaded,
+                        ...(data.yootheme_version !== undefined ? { yootheme_version: data.yootheme_version } : {}),
+                        ...(data.wp_version !== undefined ? { wp_version: data.wp_version } : {}),
+                        ...(data.cms !== undefined ? { cms: data.cms } : {}),
+                        ...(data.cms_version !== undefined ? { cms_version: data.cms_version } : {}),
+                        ...(data.php_version !== undefined ? { php_version: data.php_version } : {}),
+                        ...(data.storage_type !== undefined ? { storage_type: data.storage_type } : {}),
+                        ...(data.storage_target !== undefined ? { storage_target: data.storage_target } : {}),
+                        ...(data.available_endpoints !== undefined ? { available_endpoints: data.available_endpoints } : {}),
+                        ...(data.site_url !== undefined ? { site_url: data.site_url } : {}),
+                        ...(data.home_url !== undefined ? { home_url: data.home_url } : {}),
+                    }), site);
+                }
+                catch (e) {
+                    return withSiteMeta(errorResult({
+                        error: e,
+                        context: { site_id: site.id },
+                        hint: 'Verify YTB_MCP_SITE_URL points at a WordPress or Joomla site with the ' +
+                            'yt-builder-mcp plugin active. Try opening ' +
+                            '<site_url>/wp-json/yt-builder-mcp/v1/health (WP) or ' +
+                            '<site_url>/api/index.php/v1/yt-builder-mcp/health (Joomla) in a browser.',
+                    }), site);
+                }
+            },
+        }),
+        defineTool({
+            name: 'yootheme_builder_diagnose',
+            description: 'Full diagnostic: /health + authenticated /etag probe. Returns site_url, ' +
+                'home_url, plugin reachability, Bearer validity in one call. First call when ' +
+                'you need to know where the site lives. For per-template URLs see pages_list. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+            },
+            outputSchema: DIAGNOSE_OUTPUT_SCHEMA,
+            annotations: readOnly('Diagnose Connection'),
+            handler: async ({ site_id }) => {
+                const r = await resolveSiteOrError(pool, site_id);
+                if (!r.ok)
+                    return r.error;
+                const { client: siteClient, site } = r;
+                const checks = { plugin_reachable: false };
+                try {
+                    const health = await siteClient.get('/health');
+                    checks.plugin_reachable = true;
+                    checks.plugin_version = health.plugin_version;
+                    checks.yootheme_loaded = health.yootheme_loaded;
+                    checks.yootheme_version = health.yootheme_version;
+                    checks.endpoint_count = (health.available_endpoints ?? []).length;
+                    // 1.0.1 — mirror health URLs into diagnose output so an
+                    // agent gets URL info AND bearer-status in one call.
+                    if (health.site_url !== undefined) {
+                        checks.site_url = health.site_url;
+                    }
+                    if (health.home_url !== undefined) {
+                        checks.home_url = health.home_url;
+                    }
+                }
+                catch (e) {
+                    checks.plugin_reachable = false;
+                    checks.plugin_error = e instanceof Error ? e.message : String(e);
+                    // Plugin-unreachable path stays on jsonResult so the LLM
+                    // sees the structured error hint inline (detailResult would
+                    // hide the actionable "verify YTB_MCP_SITE_URL" hint inside
+                    // a sub-group). isError=true preserves SDK semantics.
+                    return withSiteMeta(jsonResult({
+                        ...checks,
+                        hint: 'Plugin not reachable. Verify YTB_MCP_SITE_URL and that the ' +
+                            'yt-builder-mcp plugin is active on this site.',
+                    }, { isError: true }), site);
+                }
+                try {
+                    await siteClient.get('/etag');
+                    checks.bearer_valid = true;
+                }
+                catch (e) {
+                    checks.bearer_valid = false;
+                    if (e instanceof RestError) {
+                        checks.bearer_error = `HTTP ${String(e.status)}: ${e.message}`;
+                    }
+                    else {
+                        checks.bearer_error = e instanceof Error ? e.message : String(e);
+                    }
+                    return withSiteMeta(jsonResult({
+                        ...checks,
+                        hint: 'Bearer key rejected. Regenerate the key in wp-admin → Tools → ' +
+                            '"YT Builder MCP" → Bearer Keys (or Joomla Components → YT Builder MCP) ' +
+                            'and re-run `yt-builder-mcp setup`.',
+                    }, { isError: true }), site);
+                }
+                const toolkitResult = detailResult(buildDiagnoseDetail(checks));
+                return withSiteMeta(structuredResult(toolkitResult, {
+                    ...checks,
+                    summary: 'OK — plugin reachable and Bearer key accepted.',
+                }), site);
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=health.js.map

package/dist/tools/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACH,mBAAmB,EACnB,gBAAgB,GAGnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACH,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,YAAY,GAEf,MAAM,mBAAmB,CAAC;AAE3B,wEAAwE;AAExE,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,0EAA0E;IAC1E,wEAAwE;IACxE,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,iBAAiB;IACjB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAClD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE;IAC5B,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,kEAAkE;IAClE,gEAAgE;IAChE,oEAAoE;IACpE,8CAA8C;IAC9C,QAAQ,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CACL,wDAAwD;QACpD,qEAAqE,CAC5E;IACL,QAAQ,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CACL,kEAAkE;QAC9D,mBAAmB,CAC1B;CACR,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE;IAC7B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACvC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAClD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACpC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,sEAAsE;IACtE,qEAAqE;IACrE,4DAA4D;IAC5D,QAAQ,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CACL,wDAAwD;QACpD,sEAAsE;QACtE,kDAAkD,CACzD;IACL,QAAQ,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CACL,kEAAkE;QAC9D,mBAAmB,CAC1B;CACR,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC7C,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,yBAAyB;YAC/B,WAAW,EACP,iFAAiF;gBACjF,8EAA8E;gBAC9E,4EAA4E;gBAC5E,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;aAC1B;YACD,YAAY,EAAE,oBAAoB;YAClC,WAAW,EAAE,QAAQ,CAAC,cAAc,CAAC;YACrC,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;gBAC3B,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAClD,IAAI,CAAC,CAAC,CAAC,EAAE;oBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;gBAC1B,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACvC,IAAI,CAAC;oBACD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,GAAG,CAAgB,SAAS,CAAC,CAAC;oBAC5D,kDAAkD;oBAClD,gDAAgD;oBAChD,qDAAqD;oBACrD,iDAAiD;oBACjD,wCAAwC;oBACxC,MAAM,aAAa,GAAG,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC1D,yDAAyD;oBACzD,4DAA4D;oBAC5D,6DAA6D;oBAC7D,2CAA2C;oBAC3C,OAAO,YAAY,CAAC,gBAAgB,CAAC,aAAa,EAAE;wBAChD,cAAc,EAAE,IAAI,CAAC,cAAc;wBACnC,eAAe,EAAE,IAAI,CAAC,eAAe;wBACrC,GAAG,CAAC,IAAI,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC3F,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACzE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACpD,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC5E,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC5E,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC/E,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACrF,GAAG,CAAC,IAAI,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACpG,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACnE,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACtE,CAAC,EAAE,IAAI,CAAC,CAAC;gBACd,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,OAAO,YAAY,CAAC,WAAW,CAAC;wBAC5B,KAAK,EAAE,CAAC;wBACR,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE;wBAC7B,IAAI,EACA,wEAAwE;4BACxE,4CAA4C;4BAC5C,sDAAsD;4BACtD,0EAA0E;qBACjF,CAAC,EAAE,IAAI,CAAC,CAAC;gBACd,CAAC;YACL,CAAC;SACJ,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2BAA2B;YACjC,WAAW,EACP,0EAA0E;gBAC1E,8EAA8E;gBAC9E,+EAA+E;gBAC/E,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;aAC1B;YACD,YAAY,EAAE,sBAAsB;YACpC,WAAW,EAAE,QAAQ,CAAC,qBAAqB,CAAC;YAC5C,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;gBAC3B,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAClD,IAAI,CAAC,CAAC,CAAC,EAAE;oBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;gBAC1B,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACvC,MAAM,MAAM,GAAmB,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;gBAE3D,IAAI,CAAC;oBACD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAgB,SAAS,CAAC,CAAC;oBAC9D,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC;oBAC/B,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;oBAC9C,MAAM,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;oBAChD,MAAM,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;oBAClD,MAAM,CAAC,cAAc,GAAG,CAAC,MAAM,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;oBAClE,wDAAwD;oBACxD,qDAAqD;oBACrD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;wBAChC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;oBACtC,CAAC;oBACD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;wBAChC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;oBACtC,CAAC;gBACL,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,MAAM,CAAC,gBAAgB,GAAG,KAAK,CAAC;oBAChC,MAAM,CAAC,YAAY,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACjE,yDAAyD;oBACzD,4DAA4D;oBAC5D,4DAA4D;oBAC5D,sDAAsD;oBACtD,OAAO,YAAY,CAAC,UAAU,CAAC;wBAC3B,GAAG,MAAM;wBACT,IAAI,EACA,6DAA6D;4BAC7D,+CAA+C;qBACtD,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;gBACjC,CAAC;gBAED,IAAI,CAAC;oBACD,MAAM,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;oBAC9B,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC;gBAC/B,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACT,MAAM,CAAC,YAAY,GAAG,KAAK,CAAC;oBAC5B,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;wBACzB,MAAM,CAAC,YAAY,GAAG,QAAQ,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;oBACnE,CAAC;yBAAM,CAAC;wBACJ,MAAM,CAAC,YAAY,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACrE,CAAC;oBACD,OAAO,YAAY,CAAC,UAAU,CAAC;wBAC3B,GAAG,MAAM;wBACT,IAAI,EACA,gEAAgE;4BAChE,yEAAyE;4BACzE,oCAAoC;qBAC3C,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;gBACjC,CAAC;gBAED,MAAM,aAAa,GAAG,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;gBAChE,OAAO,YAAY,CAAC,gBAAgB,CAAC,aAAa,EAAE;oBAChD,GAAG,MAAM;oBACT,OAAO,EAAE,gDAAgD;iBAC5D,CAAC,EAAE,IAAI,CAAC,CAAC;YACd,CAAC;SACJ,CAAC;KACL,CAAC;AACN,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool aggregator — collects all domain tools into a single list.
+ * The MCP server iterates this list at startup to register handlers
+ * with `@modelcontextprotocol/sdk`.
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../sites/client-pool.js';
+import type { McpServerWithElicitation } from './elicitation.js';
+import type { AnyToolDefinition } from './tool-builder.js';
+export interface BuildAllToolsOptions {
+    /**
+     * Optional MCP elicitation capability — see
+     * `src/tools/elicitation.ts` for the adapter. When supplied,
+     * destructive + ambiguity-resolution tools prompt the user via the
+     * elicitation channel; when omitted, they fall back to the
+     * preview-then-retry / `ambiguityFallbackError` flow.
+     */
+    readonly elicitation?: McpServerWithElicitation;
+}
+/**
+ * W6 — pool-based registration entrypoint. Pre-W6 this took a bare
+ * `RestClient`; W6 introduces the {@link ClientPool} as the single
+ * source of REST clients (multi-site). Each domain builder now
+ * resolves the pool per-handler via `resolveSiteOrError` and wraps
+ * every result in `withSiteMeta` (Commit 3 of the W6 trio).
+ */
+export declare function buildAllTools(pool: ClientPool, options?: BuildAllToolsOptions): readonly AnyToolDefinition[];
+export type { AnyToolDefinition, ToolDefinition } from './tool-builder.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAMjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,oBAAyB,GACnC,SAAS,iBAAiB,EAAE,CAgB9B;AAED,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,39 @@
+/**
+ * Tool aggregator — collects all domain tools into a single list.
+ * The MCP server iterates this list at startup to register handlers
+ * with `@modelcontextprotocol/sdk`.
+ *
+ * @license MIT
+ */
+import { buildSitesTools } from '../sites/tools/index.js';
+import { buildElementsTools } from './elements/index.js';
+import { buildHealthTools } from './health.js';
+import { buildInspectionTools } from './inspection.js';
+import { buildMultiItemsTools } from './multi-items/index.js';
+import { buildPagesTools } from './pages.js';
+import { buildSourcesTools } from './sources/index.js';
+/**
+ * W6 — pool-based registration entrypoint. Pre-W6 this took a bare
+ * `RestClient`; W6 introduces the {@link ClientPool} as the single
+ * source of REST clients (multi-site). Each domain builder now
+ * resolves the pool per-handler via `resolveSiteOrError` and wraps
+ * every result in `withSiteMeta` (Commit 3 of the W6 trio).
+ */
+export function buildAllTools(pool, options = {}) {
+    const deps = options.elicitation !== undefined ? { elicitation: options.elicitation } : {};
+    return [
+        ...buildHealthTools(pool),
+        ...buildPagesTools(pool),
+        ...buildElementsTools(pool, deps),
+        ...buildSourcesTools(pool, deps),
+        ...buildMultiItemsTools(pool),
+        ...buildInspectionTools(pool),
+        // W7 — Multi-Site registry tools (L1). The aggregator pulls
+        // `pool.registry` internally (W12-R1.3); the sites_list handler
+        // reads the registry without ever resolving a bearer or hitting
+        // the network, while sites_test threads the pool through to
+        // probe one specific site.
+        ...buildSitesTools(pool),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAcvD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CACzB,IAAgB,EAChB,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3F,OAAO;QACH,GAAG,gBAAgB,CAAC,IAAI,CAAC;QACzB,GAAG,eAAe,CAAC,IAAI,CAAC;QACxB,GAAG,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC;QACjC,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC;QAChC,GAAG,oBAAoB,CAAC,IAAI,CAAC;QAC7B,GAAG,oBAAoB,CAAC,IAAI,CAAC;QAC7B,4DAA4D;QAC5D,gEAAgE;QAChE,gEAAgE;QAChE,4DAA4D;QAC5D,2BAA2B;QAC3B,GAAG,eAAe,CAAC,IAAI,CAAC;KAC3B,CAAC;AACN,CAAC"}

package/dist/tools/inspection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Element-type inspection tools.
+ *
+ *   yootheme_builder_element_types_list
+ *      → catalogue of available element types (tableResult — Wave G.2)
+ *   yootheme_builder_element_type_get_schema
+ *      → field schema for a single element type (detailResult — Wave G.2)
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../sites/client-pool.js';
+import { type AnyToolDefinition } from './tool-builder.js';
+export declare function buildInspectionTools(pool: ClientPool): readonly AnyToolDefinition[];
+//# sourceMappingURL=inspection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.d.ts","sourceRoot":"","sources":["../../src/tools/inspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAU1D,OAAO,EAMH,KAAK,iBAAiB,EACzB,MAAM,mBAAmB,CAAC;AA2B3B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAwJnF"}

package/dist/tools/inspection.js

@@ -0,0 +1,170 @@
+/**
+ * Element-type inspection tools.
+ *
+ *   yootheme_builder_element_types_list
+ *      → catalogue of available element types (tableResult — Wave G.2)
+ *   yootheme_builder_element_type_get_schema
+ *      → field schema for a single element type (detailResult — Wave G.2)
+ *
+ * @license MIT
+ */
+import { detailResult, tableResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { TYPES_COMPACT_COLUMNS, TYPES_TABLE_COLUMNS, buildTypeSchemaDetail, flattenTypesPayload, mapTypeRow, } from './format/inspection-format.js';
+import { SITE_ID_SCHEMA } from './shared-schemas.js';
+import { resolveSiteOrError } from './pool-resolve-helper.js';
+import { defineTool, errorResult, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
+import { DEFAULT_FIELDS_TYPES_LIST, FIELDS, projectFields, projectedFieldsEcho, } from './sparse-fields.js';
+// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+const TYPES_LIST_OUTPUT_SCHEMA = z.object({
+    items: z.array(z.record(z.string(), z.unknown())),
+    total: z.number(),
+    projected_fields: z.array(z.string()).optional(),
+});
+const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
+    name: z.string(),
+    label: z.string().optional(),
+    origin: z.string().optional(),
+    // The REST endpoint returns `fields` as a list of {name,type,label?}
+    // field descriptors — each `name` is a valid prop key for element_add /
+    // _update_settings.
+    fields: z.array(z.record(z.string(), z.unknown())).optional(),
+    field_count: z.number(),
+});
+export function buildInspectionTools(pool) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_element_types_list',
+            description: 'List element types registered on this site (built-ins + ' +
+                'YOOessentials/uEssentials extras). Names feed `element_type` of ' +
+                'element_add. Pass `fields[]` to narrow each row. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                fields: FIELDS,
+            },
+            outputSchema: TYPES_LIST_OUTPUT_SCHEMA,
+            annotations: readOnly('List Element Types'),
+            handler: async ({ site_id, fields }) => {
+                const r = await resolveSiteOrError(pool, site_id);
+                if (!r.ok)
+                    return r.error;
+                const { client: siteClient, site } = r;
+                try {
+                    const data = await siteClient.get('/element-types');
+                    const flat = flattenTypesPayload(data);
+                    const mapped = flat.map(mapTypeRow);
+                    const mappedRecords = mapped;
+                    const items = projectFields(mappedRecords, fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const toolkitResult = tableResult(mappedRecords, {
+                        columns: [...TYPES_TABLE_COLUMNS],
+                        compactColumns: [...TYPES_COMPACT_COLUMNS],
+                        header: (count) => `${String(count)} element types`,
+                        footer: 'Use yootheme_builder_element_type_get_schema <name> for fields.',
+                    });
+                    return withSiteMeta(structuredResult(toolkitResult, {
+                        items,
+                        total: items.length,
+                        ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
+                    }), site);
+                }
+                catch (e) {
+                    return withSiteMeta(errorResult({
+                        error: e,
+                        context: { site_id: site.id },
+                        hint: 'Run yootheme_builder_diagnose to verify auth.',
+                    }), site);
+                }
+            },
+        }),
+        defineTool({
+            name: 'yootheme_builder_element_type_get_schema',
+            description: '**Call before every `element_add` / `_update_settings`** — unknown ' +
+                'prop keys are silently dropped server-side, so guessing fails ' +
+                'quietly. Returns `{name,type,label?}` field descriptors. Use ' +
+                '`element_type`; `type_name` is DEPRECATED. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                // 1.0.1 cross-tool parameter naming alignment: every other
+                // tool in this domain uses `element_type` (element_add,
+                // element_update_settings, element_list rows). This tool
+                // originally shipped with `type_name`; we accept BOTH for
+                // backward-compatibility but the canonical key going
+                // forward is `element_type`.
+                element_type: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Element type name (e.g. "headline", "text", "grid"). Use ' +
+                    'yootheme_builder_element_types_list to discover.'),
+                type_name: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('DEPRECATED alias of `element_type` — use `element_type` ' +
+                    'instead. Kept for 1.0.x backward-compatibility; will be ' +
+                    'removed in a future major.'),
+            },
+            outputSchema: TYPE_SCHEMA_OUTPUT_SCHEMA,
+            annotations: readOnly('Get Element Type Schema'),
+            handler: async (args) => {
+                // Accept either `element_type` (canonical) or `type_name`
+                // (deprecated alias). Empty/missing → 400-shaped error below.
+                const typeNameInput = typeof args.element_type === 'string' && args.element_type !== ''
+                    ? args.element_type
+                    : typeof args.type_name === 'string'
+                        ? args.type_name
+                        : '';
+                if (typeNameInput === '') {
+                    return errorResult({
+                        error: new Error('`element_type` is required (alias `type_name` also accepted).'),
+                        context: { site_id: typeof args.site_id === 'string' ? args.site_id : null },
+                        hint: 'Pass `element_type` (e.g. "headline"). Use ' +
+                            'yootheme_builder_element_types_list to discover valid values.',
+                    });
+                }
+                const type_name = typeNameInput;
+                const r = await resolveSiteOrError(pool, typeof args.site_id === 'string' ? args.site_id : undefined);
+                if (!r.ok)
+                    return r.error;
+                const { client: siteClient, site } = r;
+                try {
+                    const data = await siteClient.get(`/element-types/${encodeURIComponent(type_name)}/schema`);
+                    // The REST endpoint nests the type schema under `schema`:
+                    // {type_name, schema:{name,label,origin,has_children,fields:[…]}}.
+                    // Fall back to the top-level object for older backends.
+                    const schema = data.schema !== null && typeof data.schema === 'object'
+                        ? data.schema
+                        : data;
+                    const name = typeof schema.name === 'string' ? schema.name : type_name;
+                    const label = typeof schema.label === 'string' ? schema.label : undefined;
+                    const origin = typeof schema.origin === 'string' ? schema.origin : undefined;
+                    // `fields` is a list of {name,type,label?} field descriptors.
+                    const fields = Array.isArray(schema.fields)
+                        ? schema.fields
+                        : undefined;
+                    const fieldCount = fields !== undefined ? fields.length : 0;
+                    const toolkitResult = detailResult(buildTypeSchemaDetail({ name, label, origin, fields }));
+                    return withSiteMeta(structuredResult(toolkitResult, {
+                        name,
+                        ...(label !== undefined ? { label } : {}),
+                        ...(origin !== undefined ? { origin } : {}),
+                        ...(fields !== undefined ? { fields } : {}),
+                        field_count: fieldCount,
+                    }), site);
+                }
+                catch (e) {
+                    return withSiteMeta(errorResult({
+                        error: e,
+                        context: { element_type: type_name, site_id: site.id },
+                        hint: 'Verify element_type via yootheme_builder_element_types_list — names ' +
+                            'are case-sensitive.',
+                    }), site);
+                }
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=inspection.js.map

package/dist/tools/inspection.js.map

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

package/dist/tools/layout-flatten.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Layout-flatten helper — depth-first walk that turns a nested YOOtheme
+ * layout tree into a flat array of `{ path, parent_path, depth,
+ * element_type, props }` records.
+ *
+ * Used by `yootheme_builder_page_get_layout` when called with
+ * `flat: true`. Per Design §4.4.1:
+ *
+ *   - Walk-order: depth-first, parent BEFORE children, original child
+ *     order preserved (no sort).
+ *   - `path` uses JSON-Pointer-style notation rooted at `/layout/<key>`
+ *     and descends via `/children/<index>` segments. The root segments
+ *     mirror the keys the REST plugin produces (string keys "0","1",…
+ *     when the top-level layout is an object; numeric indices when it
+ *     happens to be an array).
+ *   - `parent_path` is `null` for top-level entries.
+ *   - The emitted record's `children` field is REMOVED — children become
+ *     their own emitted entries with their own `path`. Keeping the nested
+ *     array would defeat the purpose of flattening.
+ *   - Non-object children are skipped silently but their index is
+ *     preserved in the parent's child-numbering (the next valid sibling
+ *     keeps its original index).
+ *
+ * Pure function — no I/O, no client dependency. Test-covered in
+ * `tests/tools/layout-flatten.test.ts`.
+ *
+ * @license MIT
+ */
+/** A single emitted record in the flattened layout. */
+export interface FlatElement {
+    /** JSON-Pointer-style path, e.g. "/layout/0/children/2". */
+    path: string;
+    /**
+     * Path with the `/layout` prefix stripped, e.g. "/0/children/2".
+     * N-01 (Audit v4): mirrors the `rel_path` column element_list emits
+     * so `fields:["rel_path",...]` projection works on the flat layout.
+     */
+    rel_path: string;
+    /** Path of the parent element, or `null` for top-level entries. */
+    parent_path: string | null;
+    /** 0-based depth (top-level entries have depth 0). */
+    depth: number;
+    /** Element type string (the `type` field on the YT node, "" if missing). */
+    element_type: string;
+    /**
+     * True iff the node carries a source-binding. N-01 (Audit v4):
+     * derived via the same `hasSourceBinding` SSoT element_list uses,
+     * or an explicit REST-plugin boolean when present.
+     */
+    has_binding: boolean;
+    /** Element props (passthrough; `undefined` when the node has none). */
+    props?: Record<string, unknown>;
+    /**
+     * Children intentionally absent — see file-header. Kept in the type
+     * so consumers can confirm the field is `undefined` rather than
+     * assume it exists.
+     */
+    children?: undefined;
+    /**
+     * Allow passthrough of any other top-level fields the REST plugin
+     * may add in future (e.g. `label`, `has_binding`, `name`). The
+     * walker preserves these verbatim so projection via `pickFields`
+     * downstream stays meaningful.
+     */
+    [extra: string]: unknown;
+}
+/**
+ * Flatten a YOOtheme nested layout tree.
+ *
+ * @param layout - The top-level layout container. Accepts either an
+ *   object keyed by stringified indices ("0","1",…) or an actual array.
+ *   Returns `[]` for empty input or anything that isn't iterable.
+ */
+export declare function flattenLayout(layout: unknown): FlatElement[];
+//# sourceMappingURL=layout-flatten.d.ts.map

package/dist/tools/layout-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-flatten.d.ts","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAmB5D"}