sbuilder-mcp 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ 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

package/CHANGELOG.vi.md

@@ -6,6 +6,15 @@ 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

package/dist/domains/site/inventory.js

@@ -29,25 +29,25 @@ 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',

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.52.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",