sbuilder-mcp 0.47.0 → 0.47.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@ 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.47.2] - 2026-09-14
+
+### Fixed
+- `sb_page_create` no longer stores an HTML entity verbatim in a page name; a name like `Chính sách giao hàng & đổi trả`, lifted undecoded from a page's own source, is now decoded once before it is sent, on both the create and the home-page-adopt rename path.
+
+## [0.47.1] - 2026-09-14
+
+### Fixed
+- `sb_page_create` with `is_homepage` set on a site that already has one no longer creates a duplicate that steals the star and leaves the platform's own original home page reachable at no address; it now adopts the existing home page instead, renaming it when the caller named it something else, and reports what it did instead of creating anything.
+
 ## [0.47.0] - 2026-09-14
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,16 @@ 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.47.2] - 2026-09-14
+
+### Fixed
+- `sb_page_create` không còn lưu nguyên một HTML entity trong tên trang; một tên như `Chính sách giao hàng & đổi trả`, lấy chưa giải mã từ chính nguồn của một trang, giờ được giải mã một lần trước khi gửi đi, trên cả đường tạo trang lẫn đường đổi tên khi nhận lại trang chủ.
+
+## [0.47.1] - 2026-09-14
+
+### Fixed
+- `sb_page_create` với `is_homepage` được bật trên một site đã có sẵn trang chủ giờ không còn tạo ra một trang trùng lặp cướp mất ngôi sao và khiến trang chủ gốc của nền tảng trở nên không thể truy cập ở bất kỳ địa chỉ nào; giờ nó nhận lại trang chủ hiện có, đổi tên nếu người gọi đặt tên khác, và báo cáo việc đã làm thay vì tạo trang mới.
+
 ## [0.47.0] - 2026-09-14
 
 ### Added

package/dist/tools/page.js

@@ -311,6 +311,63 @@ async function siteChrome(ctx, siteId) {
         return {};
     }
 }
+/**
+ * Plain text, for a field the platform renders AS text.
+ *
+ * A page name is shown in the pages panel and in the browser tab and is never
+ * parsed as markup, so an HTML entity in one is always a mistake: text lifted
+ * from a page's source and handed on without being decoded. Measured on a real
+ * store, read back through sb_page_list: a page stored as "Chính sách giao hàng
+ * & đổi trả" — which is what the merchant then reads in their own editor,
+ * and what a browser tab then shows.
+ *
+ * ONE PASS, and only over what escaping actually produces. "&" decodes to
+ * "&" and stops there, because a second pass would be inventing an intent
+ * nobody expressed; an unknown entity is left exactly as it arrived. This
+ * un-escapes text that was escaped once. It does not interpret markup.
+ */
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+export function plainText(s) {
+    return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body.startsWith('#')) {
+            const code = body.startsWith('#x') ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+            // A code point that is not one is not a reference — leave the text alone
+            // rather than writing a replacement character into somebody's page name.
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        }
+        return ENTITIES[body.toLowerCase()] ?? whole;
+    });
+}
+/**
+ * The site's own home page, or null when it genuinely has none.
+ *
+ * THROWS RATHER THAN GUESSES. Answering "none" for a listing that could not be
+ * read is the one wrong answer available here: it is indistinguishable from an
+ * empty site, and the caller acts on it by creating a home page the site
+ * already had. `siteChrome` above may swallow its read because a page created
+ * without chrome is a page a person can fix; this one may not, because the page
+ * it creates cannot be un-created and takes the star off whichever page held it.
+ */
+async function existingHomepage(ctx, siteId) {
+    const listed = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(siteId)}/pages`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    const home = (listed.pages ?? []).find((p) => p.isHomepage === true);
+    if (!home || typeof home.id !== 'string' || !home.id)
+        return null;
+    return { id: home.id, name: typeof home.name === 'string' ? home.name : '' };
+}
 export function registerPageTools(server, ctx) {
     const session = new PageSession(ctx);
     server.registerTool('sb_page_open', {
@@ -981,6 +1038,8 @@ export function registerPageTools(server, ctx) {
     }, async ({ site_id: given, name, type, slug, is_homepage, settings, seed, chrome, locale, headline, dry_run }) => {
         const site_id = siteFor(ctx, given);
         const path = `/api/sites/${encodeURIComponent(site_id)}/pages`;
+        // The platform stores this verbatim and renders it as text — see plainText.
+        name = plainText(name);
         // TYPE IS THE ROUTE for several kinds of page: /checkout and
         // /products/{slug} resolve to the site's PUBLISHED page of that type and
         // fall through to a 404 when there is none. Without this argument the
@@ -1012,7 +1071,85 @@ export function registerPageTools(server, ctx) {
         // fine, while `siteChrome` asks whether the SITE has globals and it does.
         // Measured: three pages built with these tools, every one of them bare,
         // beside a store page carrying its header as ROOT's first child.
-        const wear = chrome !== false ? await siteChrome(ctx, site_id) : {};
+        // A SITE HAS ONE HOME PAGE, AND BY THE TIME AN AGENT ASKS FOR ONE IT
+        // USUALLY EXISTS ALREADY.
+        //
+        // `isHomepage: true` does not mean "make this the home page" to the
+        // platform. It means MOVE THE STAR: CreatePage demotes whoever holds it
+        // and promotes this one. An agent building a store reads the flag the
+        // first way and asks for it on a site the editor already gave a home page
+        // to, so the site ends up with two — the new one on "/", the old one
+        // demoted and holding nothing. Measured on a real store: pg_439cb121
+        // "Home" and pg_237719d4 "Trang chủ", both slug "", both path "/", the
+        // first reachable at no address at all and still listed as a page.
+        //
+        // So the flag is honoured as what the caller meant — the site's home page
+        // — which is the one it already has. Adopted, renamed when the caller
+        // named it something else, never duplicated. The same rule sb_import_site
+        // already follows when its entry page lands on a site with a home page.
+        //
+        // REPLACING the home page with a DIFFERENT page stays possible and stays
+        // explicit: create it without the flag, build it, then PATCH isHomepage
+        // through sb_api_call. That is a decision, and it should read like one.
+        const adopt = is_homepage === true ? await existingHomepage(ctx, site_id) : null;
+        const rename = adopt && name.trim() !== '' && name !== adopt.name ? name : '';
+        // Read AFTER the adopt decision and skipped when it holds: siteChrome
+        // reads the header and footer off the home page, so asking it which
+        // chrome to dress the home page in is two requests to answer "its own".
+        const wear = chrome !== false && !adopt ? await siteChrome(ctx, site_id) : {};
+        if (adopt && dry_run !== false) {
+            return text({
+                dry_run: true,
+                into: 'the existing home page',
+                page: adopt,
+                ...(rename ? { would_rename: { from: adopt.name, to: rename } } : {}),
+                note: 'Nothing would be created. This site already has a home page and a site has ' +
+                    'exactly one, so a create carrying isHomepage would have taken the star off ' +
+                    `${JSON.stringify(adopt.name)} and left it with no address. Open ${adopt.id} ` +
+                    'with sb_page_open and build it.',
+            });
+        }
+        if (adopt) {
+            // THE RENAME IS THE ONLY WRITE. Not the seed — this page may already be
+            // the site's front door, and overwriting a document nobody asked to
+            // replace is the one thing worse than the duplicate this branch exists
+            // to prevent. Not the chrome either: siteChrome reads the header and
+            // footer OFF the home page, so this page is where they came from.
+            let renamed_to;
+            let rename_failed;
+            if (rename) {
+                try {
+                    await request({
+                        base: ctx.base,
+                        method: 'PATCH',
+                        path: `${path}/${encodeURIComponent(adopt.id)}`,
+                        token: siteToken(ctx),
+                        body: { name: rename },
+                        fetchImpl: ctx.fetchImpl,
+                    });
+                    renamed_to = rename;
+                }
+                catch (e) {
+                    // The page is still the right one to build on, so a failed rename
+                    // is reported, never raised — the caller asked for a home page and
+                    // this is it, under its old name.
+                    rename_failed = e.message.replace(/^sbuilder:\s*/, '').slice(0, 160);
+                }
+            }
+            return text({
+                into: 'the existing home page',
+                page: { id: adopt.id, name: renamed_to ?? adopt.name },
+                ...(renamed_to ? { renamed: { from: adopt.name, to: renamed_to } } : {}),
+                ...(rename_failed ? { rename_failed } : {}),
+                ...(slug ? { slug_ignored: 'A home page is served at "/" and carries no slug.' } : {}),
+                ...(type && type !== 'page' ? { type_ignored: `Kept as it is; adopting does not retype a page to "${type}".` } : {}),
+                note: 'Nothing was created. This site already had a home page and a site has exactly ' +
+                    'one, so creating another would have taken the star off this page and left it ' +
+                    `with no address. Open ${adopt.id} with sb_page_open and build it. To hand the ` +
+                    'home page over to a DIFFERENT page instead, create that page WITHOUT ' +
+                    'is_homepage and then PATCH isHomepage on it through sb_api_call.',
+            });
+        }
         if (dry_run !== false) {
             return text({
                 dry_run: true,

package/package.json

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