sbuilder-mcp 0.72.0 → 0.74.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.74.0] - 2026-09-28
+
+### Added
+- `sb_review` gains an `unreachablePage` readiness gap: since a menu is a record separate from the page it links, a site can publish a page that no menu item and no href in the shared header, footer, or open page points at, so the address resolves and the sitemap lists it while no visitor ever arrives; it checks only published content pages (never the home page) and stays silent until both the menus and the shared sections have been read.
+
+## [0.73.0] - 2026-09-28
+
+### Added
+- `sb_review` gains a `no_h1` finding: every heading on a page ships as h2 (the renderer's default `htmlTag`, shared by `text` and `text-dataset`), so a page with headings and no h1 has no main title for a search engine or a screen reader, invisible on the canvas; it fires on the first heading in the page's own bands, skipping overlays.
+- `sb_review` gains a `homepage` readiness gap: a site resolves "/" by the `isHomepage` flag, so a site whose pages all carry slugs answers 404 at its own front door while every page reviews clean; it reports a draft home page separately from no home page at all, and stays silent when the page list does not carry the flag.
+
 ## [0.72.0] - 2026-09-28
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,17 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.74.0] - 2026-09-28
+
+### Added
+- `sb_review` có thêm gap readiness `unreachablePage`: vì menu là một bản ghi riêng biệt với trang mà nó trỏ tới, một site có thể publish một trang mà không mục menu nào và không href nào trong header/footer dùng chung hay trên trang đang mở trỏ tới, nên địa chỉ vẫn vào được và sitemap vẫn liệt kê trong khi không khách nào tới được; gap này chỉ xét các trang nội dung đã publish (không tính trang chủ) và im lặng cho tới khi cả menu lẫn các section dùng chung đều đã đọc được.
+
+## [0.73.0] - 2026-09-28
+
+### Added
+- `sb_review` có thêm finding `no_h1`: mọi heading trên trang đều được dựng thành h2 (giá trị mặc định `htmlTag` của renderer, dùng chung với `text` và `text-dataset`), nên một trang có heading mà không có h1 thì không có tiêu đề chính cho máy tìm kiếm hay trình đọc màn hình, và điều này vô hình trên canvas; finding báo trên heading đầu tiên trong band của chính trang đó, bỏ qua overlay.
+- `sb_review` có thêm gap readiness `homepage`: site phân giải "/" bằng cờ `isHomepage`, nên một site mà mọi trang đều có slug sẽ trả 404 ngay tại trang chủ dù mọi trang khác review sạch; gap báo riêng trường hợp trang chủ tồn tại nhưng chưa publish với trường hợp không trang nào là trang chủ, và im lặng khi danh sách trang không mang cờ này.
+
 ## [0.72.0] - 2026-09-28
 
 ### Added

package/dist/domains/site/findings.js

@@ -86,6 +86,9 @@ export const FIX = {
     hover_dead: 'Rewrite it with the same values: sb_set id "<id>", namespace style, state "hover", ' +
         'keys { … } — read them off the node first, because that one call both writes them where ' +
         'the renderer looks AND clears the slot nobody reads. Nothing else to do afterwards.',
+    no_h1: 'Make the page\'s main title an h1: sb_set id "<id>", namespace specials, keys ' +
+        '{ "htmlTag": "h1" } — ONE per page, on the heading the page is about (the first one ' +
+        'is named here; pick a different one if it is not the title). Every heading ships as h2.',
     stuck_no_host: 'Pin something: sb_set id "<id>" (or the section it lives in), namespace style, keys ' +
         '{ "position": "sticky" } — sb_set seeds the offset and the layer order with it. Until ' +
         'then the platform compiles no rule for this state at all, so the override is stored, ' +

package/dist/domains/site/readiness-fetch.js

@@ -24,7 +24,7 @@ export async function gatherReadiness(ctx, siteId, pageNodes, openPageId) {
         }
     };
     const site = encodeURIComponent(siteId);
-    const [pageList, gateways, shipping, globals, productList, categoryList, pageLinks, formList, articleList, blogCategoryList, courseList, siteRecord, overlayList, settings] = await Promise.all([
+    const [pageList, gateways, shipping, globals, productList, categoryList, pageLinks, formList, articleList, blogCategoryList, courseList, siteRecord, overlayList, settings, menuList] = await Promise.all([
         get(`/api/sites/${site}/pages`),
         get(`/api/sites/${site}/payment-gateways`),
         get(`/api/sites/${site}/shipping-methods`),
@@ -67,6 +67,9 @@ export async function gatherReadiness(ctx, siteId, pageNodes, openPageId) {
         get(`/api/sites/${site}/overlays`),
         // `<html lang>` is served from this; see siteLanguage in readiness.ts.
         get(`/api/sites/${site}/settings`),
+        // THE MENUS, for what a visitor can reach: a page nothing links to is
+        // published, listed in the sitemap, and never arrived at.
+        get(`/api/sites/${site}/menus`),
     ]);
     // A gateway counts only when it is BOTH enabled and configured — the editor's
     // `live` getter also filters by the store's currency, which is a narrowing:
@@ -111,8 +114,33 @@ export async function gatherReadiness(ctx, siteId, pageNodes, openPageId) {
     // A page an entity links to is that entity's own; only the shared template
     // counts as the category template, and a row without the flag is read as one.
     const open = openPageId ? pageList?.pages?.find((p) => p.id === openPageId) : undefined;
+    // Every level of every menu: page references by id, url links by address.
+    const menuLinks = Array.isArray(menuList?.menus)
+        ? (() => {
+            const pageIds = [];
+            const hrefs = [];
+            const walk = (items) => {
+                if (!Array.isArray(items))
+                    return;
+                for (const it of items) {
+                    if (!it || typeof it !== 'object')
+                        continue;
+                    const r = it;
+                    if (r.link?.type === 'page' && typeof r.link.pageId === 'string')
+                        pageIds.push(r.link.pageId);
+                    if (r.link?.type === 'url' && typeof r.link.url === 'string')
+                        hrefs.push(r.link.url);
+                    walk(r.items);
+                }
+            };
+            for (const m of menuList.menus)
+                walk(m?.items);
+            return { pageIds, hrefs };
+        })()
+        : null;
     return {
         pages: pageList?.pages ?? null,
+        menuLinks,
         openPageType: open && open.isDefaultTemplate !== false ? open.type : undefined,
         products,
         liveGateways,

package/dist/domains/site/readiness.js

@@ -81,9 +81,103 @@ const drafted = (pages, type) => pages.some((p) => p.type === type && p.status !
  * different question asked second. Shared chrome is a different question asked
  * FIRST, because it is true of every site and not only of a store.
  */
+/** "/about/", "/about?x=1" and "/about" are one address; "" is the home page. */
+function normalizePath(p) {
+    const s = p.split(/[?#]/)[0].replace(/\/+$/, '');
+    return s === '' ? '/' : s;
+}
+/** Every href a set of nodes carries: `specials.href`, and a menu node's own snapshot rows. */
+function hrefsIn(nodes) {
+    const out = new Set();
+    const rows = (items) => {
+        if (!Array.isArray(items))
+            return;
+        for (const it of items) {
+            if (!it || typeof it !== 'object')
+                continue;
+            const r = it;
+            if (typeof r.href === 'string' && r.href !== '')
+                out.add(normalizePath(r.href));
+            rows(r.items);
+        }
+    };
+    for (const n of nodes) {
+        const h = n.specials?.href;
+        if (typeof h === 'string' && h !== '')
+            out.add(normalizePath(h));
+        rows(n.specials?.menuItems);
+    }
+    return out;
+}
 export function readinessGaps(input) {
     const gaps = [];
     const pages = input.pages;
+    // NOTHING ANSWERS AT "/".
+    //
+    // storefront.go: the empty slug is the home page, resolved by the
+    // isHomepage flag — a site whose pages all carry slugs serves a 404 at its
+    // own front door, while every page on it is reachable and reviews clean.
+    // Reached by an agent that built pages by name and never named one home, or
+    // demoted the home page by moving the star (page.ts explains the flag). Only
+    // when the list carried the flag at all.
+    if (pages && pages.length > 0 && pages.some((p) => typeof p.isHomepage === 'boolean')) {
+        const home = pages.filter((p) => p.isHomepage === true);
+        if (!home.some((p) => p.status === 'published')) {
+            const draft = home.length > 0;
+            gaps.push({
+                id: 'homepage',
+                draft,
+                problem: draft
+                    ? 'The home page exists but is not published, so "/" — the address on every card, ' +
+                        'link and search result — answers 404 while every other page is live.'
+                    : 'No page is the home page, so "/" answers 404. Every page on the site is reachable ' +
+                        'by its slug and none of them is the front door.',
+                fix: draft
+                    ? 'Publish the home page.'
+                    : 'Make one: PATCH /api/v1/pages/{id} { "isHomepage": true } on the page that should ' +
+                        'answer at "/" — it moves the star and clears the slug. Or sb_page_create with ' +
+                        'is_homepage: true, which adopts the home page the site already has.',
+            });
+        }
+    }
+    // A PAGE NO VISITOR CAN GET TO.
+    //
+    // Every tool here authors one page and a menu is a separate record, so a
+    // site can carry a published About page that nothing links to: the sitemap
+    // lists it, the address works, and no visitor ever arrives. Reachable means
+    // a menu item references the page or its path, or something in the shared
+    // chrome or on the open page carries its path as an href (a `menu` node's
+    // own snapshot included). Content pages only, never the home page, and only
+    // when both the menus and the shared sections were read — a footer link
+    // this rule could not see must not become a finding.
+    if (pages && input.menuLinks && input.globalNodes) {
+        const reach = new Set(input.menuLinks.hrefs.map(normalizePath));
+        for (const h of hrefsIn([...input.globalNodes, ...input.pageNodes]))
+            reach.add(h);
+        const byId = new Set(input.menuLinks.pageIds);
+        const orphans = pages.filter((p) => p.status === 'published' &&
+            INDEXED_PAGE_TYPES.has(p.type) &&
+            p.isHomepage !== true &&
+            typeof p.id === 'string' &&
+            typeof p.path === 'string' &&
+            !byId.has(p.id) &&
+            !reach.has(normalizePath(p.path)));
+        if (orphans.length > 0) {
+            const named = orphans.map((p) => p.name).filter((n) => !!n).slice(0, 3);
+            gaps.push({
+                id: 'unreachablePage',
+                draft: false,
+                problem: `${orphans.length} published page${orphans.length === 1 ? '' : 's'}` +
+                    (named.length ? ` (${named.join(', ')}${orphans.length > named.length ? ', …' : ''})` : '') +
+                    ' that no menu item and no link in the shared header or footer points at. The address ' +
+                    'works and the sitemap lists it; no visitor ever arrives.',
+                fix: 'Add it to the site menu — read GET /api/sites/{siteId}/menus, append ' +
+                    '{ label, link: { type: "page", pageId } } and PUT the menu back; every bound menu ' +
+                    'node follows. Or link it from the footer with sb_event go_to_url. A page kept out ' +
+                    'on purpose (a landing page for ads) can stay out — say so.',
+            });
+        }
+    }
     // A SITE WITH NO SHARED SECTION IS NOT A SITE, IT IS A STACK OF PAGES.
     //
     // Nothing asked this. Every tool here authors ONE page, so a build that never

package/dist/domains/site/review.js

@@ -697,5 +697,35 @@ opts = {}) {
     for (const f of out)
         if (inOverlay.has(f.nodeId))
             f.overlay = true;
+    // A PAGE WITH HEADINGS AND NO <h1>. `heading` ships as h2
+    // (render/nodes/heading/html.go: SpecialString "htmlTag", default "h2"), and
+    // `text` / `text-dataset` take the same key, so a page built here — and every
+    // page the platform seeds, product title included — has headings at every
+    // level but the one a search engine and a screen reader look for first.
+    // Nothing on the canvas shows the tag. Page bands only (`band` excludes the
+    // overlays): a drawer heading is not the page's.
+    {
+        const level = (id) => {
+            const n = d.nodes[id];
+            const tag = n.specials?.htmlTag;
+            if (typeof tag === 'string' && /^h[1-6]$/.test(tag))
+                return tag;
+            return n.data.type === 'heading' ? 'h2' : null;
+        };
+        const headings = walkOrder.filter((id) => band.has(id) && level(id) !== null);
+        if (headings.length > 0 && !headings.some((id) => level(id) === 'h1')) {
+            const first = headings[0];
+            out.push({
+                code: 'no_h1',
+                nodeId: first,
+                type: d.nodes[first].data.type,
+                problem: `${headings.length} heading${headings.length === 1 ? '' : 's'} and none is an h1 — ` +
+                    'every heading ships as h2, so the page has no main title for a search engine or a ' +
+                    'screen reader. Invisible on the canvas.',
+                key: 'htmlTag',
+                fix: fill('no_h1', { id: first }),
+            });
+        }
+    }
     return out;
 }

package/dist/smoke.js

@@ -90,7 +90,9 @@ export async function runSmoke() {
     // of this check asserted the section built above was clean; it was not — the
     // heading still carried the placeholder the element ships with, and the
     // reviewer said so. The check was wrong, not the reviewer.
-    doc.apply(setKeys(doc, built.ids[1], { text: 'Autumn sale' }, { namespace: 'specials' }));
+    // And make it the page's h1 — every heading ships as h2, and a page with
+    // headings and no h1 is a finding too (no_h1). Same lesson, one rule later.
+    doc.apply(setKeys(doc, built.ids[1], { text: 'Autumn sale', htmlTag: 'h1' }, { namespace: 'specials' }));
     check('a finished section reviews clean', reviewDesign(doc).length === 0);
     // ...and an unfilled one must. A reviewer that never fires is indistinguishable
     // from one that is not wired up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",