@wootsup/yt-builder-mcp 1.3.0 → 1.4.0

package/dist/update/update-check.js

@@ -0,0 +1,155 @@
+// packages/mcp/src/update/update-check.ts
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_TIMEOUT_MS = 3_000;
+/** Parse `x.y.z` (ignoring any `-prerelease`/`+build`) into a numeric triple. */
+function parseCore(version) {
+    const m = /^\s*v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (m === null)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** Is `latest` strictly newer than `current`? Fail-closed on unparseable input. */
+export function isVersionNewer(latest, current) {
+    const a = parseCore(latest);
+    const b = parseCore(current);
+    if (a === null || b === null)
+        return false;
+    const [a0, a1, a2] = a;
+    const [b0, b1, b2] = b;
+    if (a0 !== b0)
+        return a0 > b0;
+    if (a1 !== b1)
+        return a1 > b1;
+    if (a2 !== b2)
+        return a2 > b2;
+    // Equal core → a release (latest, no prerelease) outranks a prerelease
+    // current (e.g. latest "1.3.0" vs current "1.3.0-beta.1").
+    const latestPre = latest.includes('-');
+    const currentPre = current.includes('-');
+    return currentPre && !latestPre;
+}
+/**
+ * Default registry fetch: the abbreviated packument's `dist-tags.latest`.
+ * (The `/latest` single-version endpoint behaves inconsistently under the
+ * abbreviated accept header for scoped packages; the packument + dist-tags is
+ * the robust path and the smaller abbreviated response.)
+ */
+export async function fetchLatestFromNpm(packageName, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const url = `https://registry.npmjs.org/${packageName.replace('/', '%2F')}`;
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        if (body !== null && typeof body === 'object' && 'dist-tags' in body) {
+            const tags = body['dist-tags'];
+            if (tags !== null && typeof tags === 'object' && 'latest' in tags) {
+                const latest = tags.latest;
+                if (typeof latest === 'string' && latest !== '')
+                    return latest;
+            }
+        }
+        return null;
+    }
+    catch {
+        // Offline / proxy / TLS / timeout — fail silent. The notifier is a
+        // courtesy, never a hard dependency.
+        return null;
+    }
+}
+/** Default cache: a JSON file under the user's home dir. Fail-silent on fs errors. */
+export const fileUpdateCache = {
+    read() {
+        try {
+            const raw = readFileSync(updateCachePath(), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed !== null &&
+                typeof parsed === 'object' &&
+                typeof parsed.checkedAt === 'number' &&
+                typeof parsed.latest === 'string') {
+                return parsed;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    },
+    write(entry) {
+        try {
+            const path = updateCachePath();
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, JSON.stringify(entry), 'utf8');
+        }
+        catch {
+            // A non-writable home dir must not break startup.
+        }
+    },
+};
+function updateCachePath() {
+    return join(homedir(), '.yt-builder-mcp', 'update-check.json');
+}
+/**
+ * Resolve whether a newer version is available, throttled by a cache TTL and
+ * fail-silent on every network/fs error. Never throws.
+ */
+export async function checkForUpdate(options) {
+    const { currentVersion, packageName, fetchLatest = (pkg) => fetchLatestFromNpm(pkg, options.timeoutMs), cache = fileUpdateCache, now = Date.now(), ttlMs = DEFAULT_TTL_MS, } = options;
+    const cached = safeRead(cache);
+    if (cached !== null && now - cached.checkedAt < ttlMs) {
+        return verdict(currentVersion, cached.latest, true);
+    }
+    let latest = null;
+    let error;
+    try {
+        latest = await fetchLatest(packageName);
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    if (latest === null) {
+        // Fall back to a (stale) cached value if we have one, else "unknown".
+        if (cached !== null)
+            return { ...verdict(currentVersion, cached.latest, true), error };
+        return { updateAvailable: false, current: currentVersion, latest: null, fromCache: false, error };
+    }
+    safeWrite(cache, { checkedAt: now, latest });
+    return verdict(currentVersion, latest, false);
+}
+function verdict(current, latest, fromCache) {
+    return { updateAvailable: isVersionNewer(latest, current), current, latest, fromCache };
+}
+function safeRead(cache) {
+    try {
+        return cache.read();
+    }
+    catch {
+        return null;
+    }
+}
+function safeWrite(cache, entry) {
+    try {
+        cache.write(entry);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * A one-line, actionable update notice for stderr / the diagnose tool, or null
+ * when no update is available.
+ */
+export function formatUpdateNotice(status) {
+    if (!status.updateAvailable || status.latest === null)
+        return null;
+    return (`[yt-builder-mcp] update available: ${status.current} → ${status.latest}. ` +
+        `Restart your AI client to pick it up (npx pulls @latest), or update a global install: ` +
+        `npm i -g @wootsup/yt-builder-mcp@latest.`);
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update/update-check.js.map

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

package/manifest.json

@@ -2,7 +2,7 @@
     "dxt_version": "0.1",
     "name": "@wootsup/yt-builder-mcp",
     "display_name": "YT Builder MCP for YOOtheme Pro (unofficial)",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Drive your YOOtheme Pro Page Builder programmatically from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants — read layouts, edit settings, add elements, bind dynamic sources. Works on WordPress and Joomla 5/6. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "long_description": "YT Builder MCP gives AI assistants a typed, scoped, and idempotent surface for your YOOtheme Pro Page Builder, on either WordPress or Joomla 5/6. Tools cover page discovery, layout inspection, element CRUD, source binding, and diagnostics. Bearer auth, optimistic locking via ETag, scope hierarchy (read < write < admin), and structured-error responses keep the agent safe and the workflow correct on first try. Independent third-party project — YOOtheme® is a registered trademark of YOOtheme GmbH (yootheme.com); YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.",
     "icon": "icon.png",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wootsup/yt-builder-mcp",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "type": "module",
     "description": "YT Builder MCP — drive your page builder from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "license": "MIT",
@@ -71,6 +71,7 @@
         "@clack/prompts": "^0.7.0",
         "pino": "^10.3.1",
         "proper-lockfile": "^4.1.2",
+        "undici": "^6.27.0",
         "zod": "^4.3.6"
     },
     "devDependencies": {

package/skills/yt-builder-mcp/SKILL.md

@@ -12,10 +12,10 @@ description: Drive the YOOtheme Pro Page Builder on WordPress or Joomla 5/6. Dis
 > WordPress and Joomla 5/6.
 
 This skill helps AI assistants drive the YOOtheme Pro Page Builder through the
-`@wootsup/yt-builder-mcp` server. The server catalogues 32 typed, scoped,
-idempotent tools (34 callable end-to-end with the two gateways). 29 of them
+`@wootsup/yt-builder-mcp` server. The server catalogues 33 typed, scoped,
+idempotent tools (35 callable end-to-end with the two gateways). 30 of them
 advertised as first-class entries in `tools/list`
-(25 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 5 advanced
+(26 essential L1 forwards + 2 direct L3 entries + 2 gateways), and 5 advanced
 tools reachable through the gateways. The write-capable
 `yootheme_builder_advanced` gateway routes all 5; the read-only
 `yootheme_builder_advanced_read` gateway routes only the read-only subset
@@ -81,8 +81,8 @@ The server exposes:
 - **2 direct top-level tools**, always callable, always in `tools/list`:
   `yootheme_builder_health` and `yootheme_builder_diagnose`. These are
   the "the gateway itself might be broken" escape hatch.
-- **25 essential forwarded tools**: common reads + the most-used writes
-  (pages_list, pages_create, pages_delete, page_dynamize, scaffold_section,
+- **26 essential forwarded tools**: common reads + the most-used writes
+  (pages_list, pages_resolve, pages_create, pages_delete, page_dynamize, scaffold_section,
   get_etag, element_list / add / update_settings / get / move / clone / delete,
   page_get_layout, sources_list, element_types_list, element_type_get_schema,
   template_summary, inspect_multi_items_binding, sites_list, sites_test,
@@ -105,9 +105,9 @@ The server exposes:
   auto-allow it). Prefer the read gateway for pure inspection:
   `yootheme_builder_advanced_read({ tool: "yootheme_builder_page_get_schema", arguments: { template_id } })`.
 
-`tools/list` therefore advertises 29 names (25 + 2 + 2). That's 25 L1
-essentials + 2 L3 direct + 2 gateways. The total callable surface is 34
-(29 advertised + 5 advanced reachable through the gateways). If the AI
+`tools/list` therefore advertises 30 names (26 + 2 + 2). That's 26 L1
+essentials + 2 L3 direct + 2 gateways. The total callable surface is 35
+(30 advertised + 5 advanced reachable through the gateways). If the AI
 client reports "tool not found", you are almost certainly calling an
 advanced tool by its raw name. Wrap it in
 `yootheme_builder_advanced({ tool, arguments })` (or the read gateway for
@@ -884,7 +884,7 @@ Joomla administrator access." Don't fabricate tool calls.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**32 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **34 reachable via `tools/list`** (25 L1 + 2 L3 + 2 gateways = 29 advertised; the gateways route to 5 additional advanced tools, bringing the total to 34 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
+**33 catalogued tools** plus the `yootheme_builder_advanced` (write) + `yootheme_builder_advanced_read` (read-only) gateways = **35 reachable via `tools/list`** (26 L1 + 2 L3 + 2 gateways = 30 advertised; the gateways route to 5 additional advanced tools, bringing the total to 35 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
 
 | Tool | Kind | Input keys | Description |
 | --- | --- | --- | --- |
@@ -907,13 +907,14 @@ Joomla administrator access." Don't fabricate tool calls.
 | `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Reports Multi-Items binding state: container/item pair (grid↔grid_item, slideshow↔slideshow_item, map↔map_item, …), current binding level (none\|container\|item), and a recommended_fix when the binding sits on the container instead of the child. For map/map_item, a bound item without a `location` ("lat,lng") field is flagged as a blocking map_location_warning (renders 0 markers). A List on a grid_item with nested children → blocking iterator_is_leaf_renderer (children never render). Operates on the default site unless site_id is provided. |
 | `yootheme_builder_inspect_sublayout` | read+idempotent | `element_path`, `site_id`, `template_id` | Inspects a panel/grid_item `< SUBLAYOUT`: lists the `fragment` subtree bindable leaves (with JSON-Pointer paths to bind on — NOT the container) and the render-time inner grid. Flags `ungated_grid_prop` (blocking): grid props set but the gate (title_align=left / image_align=left\|right) unsatisfied → silent no-op. For container↔item binding see inspect_multi_items_binding. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_page_dynamize` | mutating | `conditions`, `element_path`, `etag`, `leaf_map`, `list_source_name`, `page`, `remove_leaves`, `section_name`, `site_id`, `source_map`, `template_id` | One-call way to dynamize a designed section: copies the layout byte-identically and swaps only what you map. Use INSTEAD of hand-editing JSON. Give a REFERENCE (section_name from template_summary, or element_path) + list_source_name + a leaf_map (original leaf field-name → flat flow field; #parent + tuned props kept). A section with several source blocks (Played/Next/Later) dynamizes in ONE call via source_map ({match, source_name, leaf_map?}[]). Sub-query panels: key by "<subquery>.<leaf>". Returns page + `summary`. Requires page.title. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `force`, `mode`, `site_id`, `template_id` | Get the layout tree for one template. For dynamize/bind work prefer `mode:"bindings_only"` — just the binding skeleton (path, element_type, name, has_binding, source{query_name,props,has_condition}, children), no style props, typically <=15% of full size. Default `mode:"full"` returns nested `{layout, etag}`. `flat:true` gives a depth-first `{elements:[...], etag}` array (combine with `fields[]`). A repeated full read of an unchanged template auto-skips with `[unchanged]` — `force:true` re-fetches. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_schema` | read+idempotent | `site_id`, `template_id` | Get the flat schema for a template — a list of nodes with their JSON-Pointer paths and element types. Best entry-point for navigation: lighter than page_get_layout, sufficient to locate elements before editing. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `force`, `mode`, `post_id`, `site_id`, `template_id`, `url` | Get the layout tree for one template — address it by `template_id` (from pages_list), `post_id` (numeric post/article id), or `url` (public page URL, resolved in one call). For dynamize/bind work prefer `mode:"bindings_only"` — the binding skeleton only (no style props). Default `mode:"full"` returns nested `{layout, etag}`. `flat:true` gives a depth-first `{elements:[...], etag}` array (with `fields[]`). A repeated unchanged read auto-skips `[unchanged]`; `force:true` re-fetches. |
+| `yootheme_builder_page_get_schema` | read+idempotent | `post_id`, `site_id`, `template_id`, `url` | Get the flat schema for a template — nodes with their JSON-Pointer paths and element types. Lighter than page_get_layout, enough to locate elements before editing. Address it by `template_id` (from pages_list), `post_id` (numeric post/article id), or `url` (public page URL, resolved in one call). Default site unless site_id is provided. |
 | `yootheme_builder_page_publish` | idempotent | `etag`, `site_id`, `template_id` | Publish a template — persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional — when provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_page_save` | idempotent | `etag`, `layout`, `site_id`, `template_id` | Re-run save-transforms + flush caches. Optionally pass a whole `layout` to REPLACE the template tree ATOMICALLY (F85) — ideal for wholesale dynamization (read layout → swap query → remap fields → write back). A supplied layout is validated + ETag-locked; on rejection nothing is persisted. Omit `layout` to just re-run transforms (no-op if byte-identical) — for incremental edits use element_add/update/bind/delete first. New pages: pages_create. Publish: page_publish. ETag optional (412 on conflict; else last-write-wins). Operates on the default site unless site_id is provided. |
 | `yootheme_builder_pages_create` | idempotent | `dry_run`, `layout`, `menu_item`, `published`, `site_id`, `slug`, `status`, `title` | Create a page (WordPress) or article (Joomla 5/6) with a YOOtheme per-page layout. Required: title. Optional: slug, status (default draft), published (default false → live on true: WP publish / Joomla state 1), layout (JSON), menu_item (Joomla SEF route), dry_run (preflight, no persist). Returns page_id (WP) / article_id (Joomla), slug, template_id (page:{id} or article:{id}), etag, warnings. Joomla: a published article has NO SEF route until a menu item points at it — pass menu_item, else frontend_url may 404. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_pages_delete` | idempotent | `confirm`, `force`, `post_id`, `site_id` | Delete a page (WordPress) or article (Joomla 5/6) with its YOOtheme per-page layout. Requires confirm:true (gate against accidental deletion). Default: trash (recoverable). force:true: permanent delete. Refuses non-page/article types with 403 (Layer 9 defense). Returns deleted:true, page_id (WP) / article_id (Joomla), force_deleted, bumped etag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_pages_list` | read+idempotent | `fields`, `site_id` | List all pages, templates, and layouts in the YOOtheme Pro builder. Returns template_id, label, type, element count, frontend_url, and builder_url (deep-link to open it in the builder) per row. CALL THIS FIRST to discover available template IDs before any tool that needs a template_id (page_get_layout, element_list, page_get_schema, etc.). Keywords: list pages, list templates, discover template_id. Pass `fields:["id","label"]` to slim. Returns ALL pages in one call (no pagination, typically <50 templates per site). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_list` | read+idempotent | `cursor`, `fields`, `label_contains`, `limit`, `site_id` | List pages, templates, and layouts in the YOOtheme Pro builder (template_id, label, type, element count, frontend_url, builder_url per row). CALL THIS FIRST to discover template IDs before page_get_layout / element_list / page_get_schema. Paginates: up to `limit` rows (default 50) plus `total` and a `next_cursor` (pass it back as `cursor`) when more remain. Filter with `label_contains`. Slim rows with `fields:["id","label"]`. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_resolve` | read+idempotent | `site_id`, `url` | Resolve a public page/article URL to the template_id that renders it — paste a URL, get a layout-addressable id in one call. Returns {template_id (page:{id}/article:{id}), post_id, type, frontend_url}. 404s with a hint for THEME-template URLs (use pages_list instead). page_get_layout / page_get_schema also accept a `url` param directly. Default site unless site_id given. |
 | `yootheme_builder_scaffold_section` | mutating | `columns`, `etag`, `site_id`, `template_id` | Create a VALID section → row → column hull in ONE atomic call and return the column JSON-Pointer path(s) to drop content into. This is the EASIEST correct way to start a new layout block: YOOtheme content must live in section → row → column, and adding content anywhere else (root, bare section, bare row) is rejected. Pass `columns` (1-12, default 1) for a multi-column row. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_sites_list` | read+idempotent | `site_id` | List all sites configured in this multi-site MCP installation. Returns site_id + URL + platform (wordpress\|joomla) + default flag per row. CALL THIS FIRST when working with a fresh MCP connection to discover available site_ids before targeting one with any other tool. Read-only, no REST calls. Keywords: list sites, list connections, list installations, discover site_id, available sites, configured sites, what sites exist, multi-site index. (site_id is accepted for schema-uniformity but ignored by this tool.) |
 | `yootheme_builder_sites_test` | read+idempotent | `site_id` | Verify connectivity to ONE site: probes /health (no auth) + /etag (auth) in parallel; returns plugin_reachable + bearer_valid. `site_id` is REQUIRED. Use sites_list to find IDs. |