sbuilder-mcp 0.13.0 → 0.14.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.14.0] - 2026-09-09
+
+### Added
+- sb_review now reports `categoryScope` when a store has more than one product category and none of them is linked to a page of its own, since `/collections/{slug}` then falls back to the category type's default template for every category, and nothing on that shared template narrows the product feed to the category in the URL, so a shopper sees the whole catalogue (or another category's products) no matter which one they open; the finding names the fix — a page per category with its repeater set to `{ "collectionType": "collection", "collectionId": "<category id>" }`, linked with `sb_api_call post:/api/sites/{siteId}/page-links/bulk`.
+
+## [0.13.1] - 2026-09-09
+
+### Fixed
+- sb_store's checkout build now seeds a `form:success` event that sends the shopper to `/checkout/complete`, since the form record's own `settings.afterSubmit.action = "redirect"` is stored by the API but carried nowhere by the platform, leaving a completed order on the checkout page with every cart total reading 0.
+- sb_review now reports `order_goes_nowhere` for a checkout-shaped page (a form alongside a cart total) whose form has no navigating `form:success` event, naming the sb_event call that fixes it.
+
 ## [0.13.0] - 2026-09-09
 
 ### 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.14.0] - 2026-09-09
+
+### Added
+- sb_review giờ báo cáo `categoryScope` khi một store có nhiều hơn một product category mà không category nào được link tới một page riêng, vì khi đó `/collections/{slug}` sẽ rơi về default template của loại category cho mọi category, và không có gì trên template dùng chung đó thu hẹp product feed theo category trong URL, nên khách hàng sẽ thấy toàn bộ catalogue (hoặc sản phẩm của category khác) dù mở category nào; finding nêu rõ cách khắc phục — mỗi category một page riêng với repeater đặt `{ "collectionType": "collection", "collectionId": "<id category>" }`, liên kết bằng `sb_api_call post:/api/sites/{siteId}/page-links/bulk`.
+
+## [0.13.1] - 2026-09-09
+
+### Fixed
+- Việc dựng checkout của sb_store giờ tự gieo một event `form:success` đưa khách hàng tới `/checkout/complete`, vì `settings.afterSubmit.action = "redirect"` của chính form record được API lưu lại nhưng nền tảng không mang nó đi đâu cả, khiến một đơn hàng đã hoàn tất vẫn ở lại trang checkout với mọi tổng giỏ hàng hiện 0.
+- sb_review giờ báo cáo `order_goes_nowhere` cho một trang có dáng checkout (có form và có cart total) mà form của nó không có event `form:success` nào điều hướng đi, nêu rõ lệnh sb_event để khắc phục.
+
 ## [0.13.0] - 2026-09-09
 
 ### Added

package/dist/domains/site/findings.js

@@ -60,6 +60,11 @@ export const FIX = {
         '{ "overflowX": "visible", "overflowY": "visible" } — or move the pinned node outside it. ' +
         'Sticky resolves against its nearest SCROLLING ancestor, so a clipping one becomes that ' +
         'ancestor and the node pins inside a box that never scrolls.',
+    order_goes_nowhere: 'Send the shopper on: sb_event id "<id>", trigger "form:success", action "go_to_url", ' +
+        'payload { "url": "/checkout/complete" }. That path resolves by page TYPE and serves a ' +
+        'built-in receipt even with no completion page, so it is never a link to a 404. Do NOT ' +
+        'reach for the form record\'s settings.afterSubmit "redirect" — the API stores it and the ' +
+        'platform carries it nowhere.',
     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.',

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

@@ -24,7 +24,7 @@ export async function gatherReadiness(ctx, siteId, pageNodes) {
         }
     };
     const site = encodeURIComponent(siteId);
-    const [pageList, gateways, shipping, globals, productList] = await Promise.all([
+    const [pageList, gateways, shipping, globals, productList, categoryList, pageLinks] = await Promise.all([
         get(`/api/sites/${site}/pages`),
         get(`/api/sites/${site}/payment-gateways`),
         get(`/api/sites/${site}/shipping-methods`),
@@ -34,6 +34,14 @@ export async function gatherReadiness(ctx, siteId, pageNodes) {
         // key-only one. A page is enough to tell empty from not; `total` carries the
         // real count when the platform sends it.
         get(`/api/sites/${site}/products?limit=200`),
+        // THE CATEGORIES, and the pages they point at. `/collections/{slug}` resolves
+        // through PublishedForEntity: the category's OWN page when a page-link names
+        // one, else the DEFAULT TEMPLATE for the `category` type — and nothing on
+        // that shared template narrows the product feed to the category in the URL.
+        // So two categories with no page-links means at most one of them can be
+        // right, and the rest list the whole catalogue.
+        get(`/api/sites/${site}/product-categories`),
+        get(`/api/sites/${site}/page-links`),
     ]);
     // 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:
@@ -44,6 +52,12 @@ export async function gatherReadiness(ctx, siteId, pageNodes) {
         : null;
     const methods = shipping?.shippingMethods ?? shipping?.methods;
     const shippingMethods = Array.isArray(methods) ? methods.length : null;
+    const cats = categoryList?.categories ?? categoryList?.productCategories;
+    const categories = Array.isArray(cats) ? (categoryList?.total ?? cats.length) : null;
+    const links = pageLinks?.links ?? pageLinks?.pageLinks;
+    const categoryPageLinks = Array.isArray(links)
+        ? links.filter((l) => l?.linkType === 'productCategory').length
+        : null;
     const globalNodes = globals?.globalSections
         ? globals.globalSections.flatMap((g) => Object.values(g.document?.nodes ?? {}))
         : null;
@@ -64,5 +78,7 @@ export async function gatherReadiness(ctx, siteId, pageNodes) {
         shippingMethods,
         pageNodes,
         globalNodes,
+        categories,
+        categoryPageLinks,
     };
 }

package/dist/domains/site/readiness.js

@@ -190,6 +190,39 @@ export function readinessGaps(input) {
             fix: 'Put a control with the open_cart event in the header global section.',
         });
     }
+    // EVERY CATEGORY SHOWS EVERY PRODUCT, which is what a shared template does.
+    //
+    // `/collections/{slug}` resolves through PublishedForEntity: the category's
+    // OWN page when a page-link names one, else the DEFAULT TEMPLATE for the
+    // `category` type. Nothing on that shared template narrows the product feed to
+    // the category in the URL — `entityScope` threads the entity into the article
+    // feed for a blogCategory and the review feed for a product, and into nothing
+    // at all for a productCategory — so a repeater on `all_products` repeats the
+    // whole catalogue, and one on `collection` names ONE fixed id. Either way at
+    // most one category can be right.
+    //
+    // Reported on the COUNTS rather than by reading the template's document: two
+    // categories and no page-links is already the defect, whatever the template
+    // says, and a document fetch per review to confirm it would cost every store
+    // that has this right. Silent when either count could not be read, like every
+    // other check here.
+    if ((input.categories ?? 0) > 1 && input.categoryPageLinks === 0) {
+        gaps.push({
+            id: 'categoryScope',
+            draft: false,
+            problem: `${input.categories} product categories share ONE page — none of them points at a page ` +
+                'of its own, so /collections/{slug} serves the default template for every one. Nothing ' +
+                'on that template narrows the product feed to the category in the URL (the blog twin ' +
+                'auto-scopes; this one does not), so a shopper who picks a category sees the whole ' +
+                'catalogue, or one other category, on all of them.',
+            fix: 'Give each category its own page and set its product repeater to config ' +
+                '{ "collectionType": "collection", "collectionId": "<that category id>" }, then link ' +
+                'them in one call: sb_api_call post:/api/sites/{siteId}/page-links/bulk with body ' +
+                '{ "linkType": "productCategory", "linkIds": ["<category ids>"], "pageId": "<page id>" } ' +
+                '— one call per page, since each page is one category. sb_duplicate the template you ' +
+                'already have rather than rebuilding it.',
+        });
+    }
     return gaps;
 }
 export const READINESS_NOTICE = 'These are STORE gaps, not page defects: each one survives publish without a warning and is ' +

package/dist/domains/site/review.js

@@ -225,6 +225,39 @@ export function reviewDesign(doc) {
             styled.states?.[STUCK_STATE],
             ...Object.values(styled.responsive ?? {}).map((r) => r?.states?.[STUCK_STATE]),
         ];
+        // AN ORDER FORM THAT LEAVES THE SHOPPER WHERE THEY WERE.
+        //
+        // Measured on a store built entirely with these tools: the order is created
+        // and the page stays put, showing a receipt-shaped list of totals that all
+        // read 0 because the cart it was summing has just been emptied. Nothing
+        // errors, and the shopper cannot tell a completed order from a failed one.
+        //
+        // Checked on the FORM NODE rather than on the form record, because the
+        // record's own `afterSubmit: "redirect"` is stored by the API and carried
+        // nowhere (`forms/pagesource.go`) — reading it would report a page as fine
+        // on the strength of a setting the platform ignores.
+        if (type === 'form') {
+            const events = n.events ?? [];
+            const navigates = events.some((e) => e.name === 'form:success' &&
+                (e.action === 'go_to_url' || e.action === 'open_page' || e.action === 'go_to_checkout'));
+            // AN ORDER-SHAPED PAGE, read off the document rather than off the page
+            // record. The record's `type` would need a second round trip on every
+            // open, and the form's own type a third; a page that carries BOTH a form
+            // and a cart total is the checkout shape and nothing else is — a contact
+            // page has no cart to total.
+            const sellsFromCart = Object.values(d.nodes).some((x) => x.data?.type === 'cart-total');
+            if (!navigates && sellsFromCart) {
+                out.push({
+                    code: 'order_goes_nowhere',
+                    nodeId: id,
+                    type,
+                    problem: 'This is the checkout form and nothing sends the shopper anywhere once the order ' +
+                        'is placed. They stay on this page, where every cart total now reads 0 because the ' +
+                        'cart was just emptied — a completed order that looks like a failed one.',
+                    fix: fill('order_goes_nowhere', { id }),
+                });
+            }
+        }
         // A HOVER STORED WHERE NOBODY READS IT. The universal hover state is not the
         // only home: an element whose meta declares a Hover variant keeps it
         // somewhere its own renderer looks, and for a `button` that is the flat

package/dist/tools/store.js

@@ -132,8 +132,54 @@ function pageDocumentFor(formId, headline) {
         .join(formId)
         .split(HEADLINE_SENTINEL)
         .join(headline);
-    return JSON.parse(json);
+    const doc = JSON.parse(json);
+    sendTheShopperOn(doc);
+    return doc;
+}
+/**
+ * WHERE THE SHOPPER GOES AFTER THE ORDER, which nothing else supplies.
+ *
+ * Measured on a store built entirely with these tools: press "Đặt hàng" and the
+ * order is created — and the shopper stays on the checkout page, looking at a
+ * receipt-shaped list of totals that all read 0 ₫ because the cart it was
+ * summing has just been emptied, under an inline confirmation whose default
+ * wording runs the order number into the total ("Đơn hàng #1003129.000 ₫").
+ * Nothing is broken; nothing sent them anywhere.
+ *
+ * The form record HAS a setting for this and it does not work:
+ * `settings.afterSubmit.action = "redirect"` is accepted by the API, stored, and
+ * carried nowhere — `forms/pagesource.go` says so outright ("Only the MESSAGE
+ * behaviour is carried today"), and `page.FormRef.RedirectPath` is assigned by
+ * nothing in the platform. Writing `specials.sentRedirect` on the node does not
+ * survive either: the composer overwrites that special from the same empty
+ * field on every render. So the platform's seed cannot carry this, and neither
+ * can any setting an agent can reach.
+ *
+ * What does work is the form's own success chain, which the island runs BEFORE
+ * afterSubmit and which `form`'s meta declares `go_to_url` on. `/checkout/complete`
+ * is the right destination unconditionally: it resolves by page TYPE, and it
+ * backstops itself with a built-in receipt when the store has no completion page
+ * of its own, so this is never a link to a 404.
+ */
+function sendTheShopperOn(doc) {
+    for (const node of Object.values(doc.nodes)) {
+        if (node.data?.type !== 'form')
+            continue;
+        const events = (node.events ?? []);
+        if (events.some((e) => e.name === 'form:success'))
+            continue;
+        events.unshift({
+            id: 'ev_go_to_url',
+            name: 'form:success',
+            action: 'go_to_url',
+            payload: { url: COMPLETE_PATH },
+        });
+        node.events = events;
+    }
 }
+/** The path a completed order lands on. Resolves by page TYPE, and serves a
+ * built-in receipt when the store has authored no completion page. */
+const COMPLETE_PATH = '/checkout/complete';
 /**
  * THE FORM TEMPLATES, as a tuple zod can turn into an enum.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.13.0",
+  "version": "0.14.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",