sbuilder-mcp 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.53.0] - 2026-09-15
+
+### Added
+- `sb_store action:"form"` now takes a `page_name` (and optional `headline`) that builds a page and places the seeded form on it in the same call, instead of leaving the caller to create a page, `sb_add` a form element, and `sb_set` its `formId` by hand.
+- `sb_page_list`'s advisory for a missing login, register, forgot-password, or contact page now names the single `sb_store action:"form" template:"..." page_name:"..."` call that builds both the form and its page, instead of pointing at the form template alone.
+
+### Changed
+- A page created for a seeded form is a second write and never undoes the first; if the page create is refused, `sb_store` still reports the form it already made, under a `page_failed` field, rather than rolling the form back.
+
+## [0.52.0] - 2026-09-15
+
+### Added
+- `sb_page_list`'s `usually_also` advisory now names a missing `faq` page.
+- `sb_page_list`'s `usually_also` advisory now names a missing blog listing page, but only on a site that already has a `post` (article) template to list — a site with no articles is no longer told to build one.
+
+### Changed
+- `sb_page_list`'s `usually_also` advisory splits the single `policy` entry into `policy-delivery` (shipping and returns) and `policy-privacy` (privacy and terms of use), so a site carrying only one of the two no longer reads as having both.
+
 ## [0.51.0] - 2026-09-15
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,24 @@ 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.53.0] - 2026-09-15
+
+### Added
+- `sb_store action:"form"` giờ nhận thêm `page_name` (và `headline` tuỳ chọn) để dựng luôn một trang và đặt form vừa tạo lên đó trong cùng một lần gọi, thay vì để người gọi phải tự tạo trang, `sb_add` phần tử form rồi `sb_set` `formId` của nó.
+- Gợi ý của `sb_page_list` khi thiếu trang đăng nhập, đăng ký, quên mật khẩu hoặc liên hệ giờ nêu đích danh một lệnh gọi duy nhất `sb_store action:"form" template:"..." page_name:"..."` để dựng cả form lẫn trang chứa nó, thay vì chỉ trỏ tới mỗi template của form.
+
+### Changed
+- Trang được tạo cho một form vừa dựng là một lần ghi riêng và không bao giờ huỷ lần ghi trước đó; nếu việc tạo trang bị từ chối, `sb_store` vẫn báo cáo form đã tạo thành công, kèm trường `page_failed`, thay vì xoá form đó đi.
+
+## [0.52.0] - 2026-09-15
+
+### Added
+- Gợi ý `usually_also` của `sb_page_list` giờ nêu tên trang `faq` nếu site còn thiếu.
+- Gợi ý `usually_also` của `sb_page_list` giờ nêu tên trang danh sách blog nếu site còn thiếu, nhưng chỉ khi site đã có template bài viết (`post`) để liệt kê — site chưa có bài viết nào thì không còn bị nhắc xây trang này.
+
+### Changed
+- Gợi ý `usually_also` của `sb_page_list` tách mục `policy` duy nhất thành `policy-delivery` (giao hàng và đổi trả) và `policy-privacy` (bảo mật và điều khoản sử dụng), để một site chỉ có một trong hai trang không còn bị đọc nhầm là đã có đủ cả hai.
+
 ## [0.51.0] - 2026-09-15
 
 ### Added

package/dist/domains/site/inventory.js

@@ -29,40 +29,71 @@ export const USUAL_PAGES = [
         key: 'login',
         match: ['login', 'signin', 'sign-in', 'dang-nhap', 'đăng nhập'],
         why: 'Nothing for a header, an order email or /account\'s signed-out state to link to. ' +
-            'Seed it with sb_store action:"form" template "login" on a page of type "page".',
+            'sb_store action:"form" template:"login" page_name:"Đăng nhập" builds the form AND the page it lives on.',
     },
     {
         key: 'register',
         match: ['register', 'signup', 'sign-up', 'dang-ky', 'đăng ký'],
         why: 'A shopper cannot open an account, so order history, addresses and any member-gated ' +
-            'page are unreachable. Template "register".',
+            'page are unreachable. sb_store action:"form" template:"register" with a page_name.',
     },
     {
         key: 'forgot',
         match: ['forgot', 'reset', 'quen-mat-khau', 'quên mật khẩu', 'doi-mat-khau'],
         why: 'A customer who forgets a password has no way back in and writes to support instead. ' +
-            'Template "forgot".',
+            'sb_store action:"form" template:"forgot" with a page_name.',
     },
     {
         key: 'contact',
         match: ['contact', 'lien-he', 'liên hệ'],
         why: 'No address, phone or form anywhere, so a shopper with a question about an order has ' +
-            'nowhere to put it. Template "contact".',
+            'nowhere to put it. sb_store action:"form" template:"contact" with a page_name.',
     },
     {
         key: 'about',
         match: ['about', 'gioi-thieu', 'giới thiệu', 've-chung-toi'],
         why: 'Nothing says who the shop is, which is the page a first-time buyer opens before paying.',
     },
+    // TWO POLICIES, NOT ONE BUCKET. These were a single entry, and it read a shop
+    // carrying only "Chính sách giao hàng & đổi trả" as complete — which is
+    // exactly the shop that was measured, and it had no privacy terms at all. One
+    // policy page satisfying a check about all of them is the check answering a
+    // question it was not asked.
     {
-        key: 'policy',
+        key: 'policy-delivery',
         match: [
-            'policy', 'policies', 'chinh-sach', 'chính sách', 'dieu-khoan', 'điều khoản',
-            'terms', 'privacy', 'bao-mat', 'bảo mật', 'doi-tra', 'đổi trả', 'return',
-            'shipping', 'van-chuyen', 'vận chuyển', 'giao-hang', 'giao hàng', 'refund',
+            'doi-tra', 'đổi trả', 'return', 'refund', 'hoan-tien', 'hoàn tiền',
+            'shipping', 'van-chuyen', 'vận chuyển', 'giao-hang', 'giao hàng', 'delivery',
         ],
-        why: 'No delivery, return or privacy terms a shopper can read before paying — the pages a ' +
-            'marketplace and a payment provider both ask for.',
+        why: 'No delivery or return terms a shopper can read before paying. This is the page a buyer ' +
+            'looks for when the parcel is late and the one a dispute is settled against.',
+    },
+    {
+        key: 'policy-privacy',
+        match: [
+            'privacy', 'bao-mat', 'bảo mật', 'dieu-khoan', 'điều khoản', 'terms',
+            'quy-dinh', 'quy định',
+        ],
+        why: 'No privacy policy or terms of use. Payment providers and marketplaces ask for both ' +
+            'before they will list a shop, and a checkout form collects personal data either way.',
+    },
+    {
+        key: 'faq',
+        match: ['faq', 'cau-hoi', 'câu hỏi', 'hoi-dap', 'hỏi đáp', 'help', 'tro-giup', 'trợ giúp'],
+        why: 'The same handful of questions reach support one message at a time, with no page to link ' +
+            'an answer to. The accordion element is what this page is built from.',
+    },
+    {
+        key: 'blog',
+        // ONLY ONCE THERE IS SOMETHING TO LIST. `post` is the ARTICLE template —
+        // it answers /blog/{slug} and has no address of its own — so a site with
+        // one can publish articles that nothing on the site links to. A site
+        // without one has no articles, and telling it to build a listing page is
+        // advice about a section it never asked for.
+        when: (pages) => pages.some((x) => x.type === 'post'),
+        match: ['blog', 'tin-tuc', 'tin tức', 'news', 'bai-viet', 'bài viết', 'kien-thuc', 'cẩm nang'],
+        why: 'This site has an article template, so /blog/{slug} works — but no page LISTS the ' +
+            'articles, so each one is reachable only by someone who already has its URL.',
     },
 ];
 /**
@@ -80,5 +111,5 @@ export function missingUsualPages(pages) {
         .filter((p) => (typeof p.type === 'string' ? p.type === 'page' : true))
         .map((p) => `${typeof p.slug === 'string' ? p.slug : ''} ${typeof p.name === 'string' ? p.name : ''}`.toLowerCase())
         .join('\n');
-    return USUAL_PAGES.filter((u) => !u.match.some((m) => hay.includes(m)));
+    return USUAL_PAGES.filter((u) => (u.when ? u.when(pages) : true) && !u.match.some((m) => hay.includes(m)));
 }

package/dist/tools/store.js

@@ -33,6 +33,7 @@ import { request, redact } from '../transport/http.js';
 import { siteToken } from './credentialpick.js';
 import { siteFor } from './context.js';
 import { genId } from '../domains/site/ids.js';
+import { addSubtree } from '../domains/site/builder.js';
 import { chromeLinks, hasGlobal, shareChrome, sitePages } from './chrome.js';
 import { tokensFromPage } from '../domains/site/importmap.js';
 import { CHECKOUT_FORM, CHECKOUT_FORM_DOCUMENT, CHECKOUT_PAGE_DOCUMENT, CHECKOUT_TEXT, FORM_ID_SENTINEL, HEADLINE_SENTINEL, FORM_TEMPLATES, } from '../catalog/checkout.generated.js';
@@ -207,7 +208,54 @@ const FORM_TEMPLATE_KEYS = Object.keys(FORM_TEMPLATES).sort();
  * returns — and `/account` is the one page that is not a free choice, because
  * `membersOnlyRedirectTarget` sends every gated visitor there.
  */
-async function seedForm(ctx, siteId, key, formName, dryRun) {
+/**
+ * The page a seeded form goes on, built and saved in the same call.
+ *
+ * WHY THIS EXISTS. seedForm made a form and stopped, and said so: "No page is
+ * made. Where a login form belongs is a design decision." True, and it left the
+ * caller three steps — create a page, sb_add a form element, sb_set its formId —
+ * with nothing insisting they belong together. Measured: a store built with
+ * these tools had no login page, no register page and no forgot page, and its
+ * own header had nothing to link to. The design decision was never the
+ * obstacle; the three steps were.
+ *
+ * A BLANK PAGE FIRST, THEN THE SUBTREE, rather than a document posted with the
+ * create. The checkout path can post one because it has a whole seeded document
+ * to post; here the document is one element, and going through the session is
+ * how every other builder in this server writes a page — band rules, id
+ * minting and the save contract all come with it instead of being re-derived.
+ */
+async function placeFormOnPage(ctx, session, siteId, formId, pageName, headline) {
+    const made = (await request({
+        base: ctx.base,
+        method: 'POST',
+        path: `/api/sites/${encodeURIComponent(siteId)}/pages`,
+        token: siteToken(ctx),
+        body: { name: pageName, type: 'page' },
+        fetchImpl: ctx.fetchImpl,
+    }));
+    const id = made.page?.id;
+    if (typeof id !== 'string' || !id) {
+        throw new Error('sbuilder: the platform accepted the page create and returned no page');
+    }
+    await session.open(siteId, id);
+    const doc = session.current();
+    const { patches } = addSubtree(doc, doc.doc.root_node_id, {
+        type: 'flex-section',
+        children: [
+            {
+                type: 'flex-block',
+                children: [
+                    ...(headline ? [{ type: 'heading', specials: { text: headline } }] : []),
+                    { type: 'form', specials: { formId } },
+                ],
+            },
+        ],
+    });
+    await session.applyAndSave(patches);
+    return { id, name: typeof made.page?.name === 'string' ? made.page.name : pageName };
+}
+async function seedForm(ctx, session, siteId, key, formName, pageName, headline, dryRun) {
     const tpl = FORM_TEMPLATES[key];
     const site = encodeURIComponent(siteId);
     const name = formName ?? tpl.key;
@@ -236,6 +284,15 @@ async function seedForm(ctx, siteId, key, formName, dryRun) {
                     path: `/api/sites/${site}/forms/{formId}/document`,
                 },
             ],
+            ...(pageName
+                ? {
+                    would_also: `create a page named ${JSON.stringify(pageName)} of type "page" and put ` +
+                        'the form on it, so the form has an address a header can link to',
+                }
+                : {
+                    no_page: 'Only the form. Pass page_name to have the page made and the form placed ' +
+                        'on it in this same call — the three steps that otherwise get skipped.',
+                }),
             preview: redact({ name, type: tpl.type }),
         };
     }
@@ -268,12 +325,34 @@ async function seedForm(ctx, siteId, key, formName, dryRun) {
         await send('DELETE', `/api/sites/${site}/forms/${encodeURIComponent(form.id)}`).catch(() => undefined);
         throw e;
     }
+    // THE PAGE IS A SECOND WRITE AND MUST NOT UNDO THE FIRST. The form EXISTS the
+    // moment its three calls land; a refused page create leaves a form the caller
+    // can still place by hand, which is exactly what they had before this
+    // argument existed. Reporting the failure beats deleting a form they asked
+    // for — the same rule the seed follows in sb_page_create.
+    let page;
+    let page_failed;
+    if (pageName) {
+        try {
+            page = await placeFormOnPage(ctx, session, siteId, form.id, pageName, headline);
+        }
+        catch (e) {
+            page_failed = e.message.replace(/^sbuilder:\s*/, '').slice(0, 160);
+        }
+    }
     return {
         form: { id: form.id, type: form.type, name: form.name },
         fields,
-        next: `Place it: sb_add a "form" element, then sb_set its specials.formId to "${form.id}". ` +
-            'The submit button lives in the FORM DOCUMENT, not on the page, and a page republish is ' +
-            'what makes a form-document edit visible.',
+        ...(page ? { page } : {}),
+        ...(page_failed ? { page_failed } : {}),
+        next: page
+            ? `The form is on page ${page.id}. Publish it with sb_publish, and link to it from the ` +
+                'header. The submit button lives in the FORM DOCUMENT, not on the page, and a page ' +
+                'republish is what makes a form-document edit visible.'
+            : `Place it: sb_add a "form" element, then sb_set its specials.formId to "${form.id}" — ` +
+                'or pass page_name to have that page made for you. The submit button lives in the FORM ' +
+                'DOCUMENT, not on the page, and a page republish is what makes a form-document edit ' +
+                'visible.',
     };
 }
 export function registerStoreTools(server, ctx, session) {
@@ -350,7 +429,7 @@ export function registerStoreTools(server, ctx, session) {
             if (!template) {
                 throw new Error(`sbuilder: action:"form" needs a template. One of: ${FORM_TEMPLATE_KEYS.join(', ')}.`);
             }
-            return text(await seedForm(ctx, siteId, template, name, dry_run !== false));
+            return text(await seedForm(ctx, session, siteId, template, name, page_name, headline, dry_run !== false));
         }
         const lang = (language ?? 'vi');
         const t = CHECKOUT_TEXT[lang];

package/package.json

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