sbuilder-mcp 0.61.1 → 0.63.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ 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.63.0] - 2026-09-21
+
+### Added
+- `sb_store` gained `global_attach` and `global_detach` actions to put an existing shared header or footer onto the open page, or take one off, without hand-writing the composed stamp.
+- `sb_page_state` is a new tool that reports whether the editor's draft, the published page, and this session's own copy of a page agree, and lists the real recovery points (autosave checkpoints and labelled versions) when they do not.
+- `sb_publish` now reports the published revision's `id`, `publishedAt`, and the draft version it was compiled from, and takes a `verify` argument that fetches the live storefront and confirms the origin is actually serving that revision.
+
+### Fixed
+- `sb_event` now writes the `<a href>` a renderer actually reads alongside a navigation click, since `node.events` is never read for a sole `go_to_url`/`open_page` click; every navigation authored before this fix rendered, saved, and published a control that did nothing when a shopper clicked it.
+- `sb_review` no longer throws on a page whose document names a child node it does not hold; it reports the defect as `missing_node` instead.
+- `sb_review` reports `dead_nav` for a navigation click that reached the document without its href projection.
+- `sb_look`'s overlap check and its `node_id` framing now recognize an overlay (such as the cart drawer) by how it actually renders off-screen, not only by its composition stamp, removing dozens of false off-canvas findings per page and letting a drawer authored straight into a page document be framed at all.
+- API errors thrown by a tool now carry the platform's own error `code` and HTTP status in the message, so a failure like a band-order refusal can be matched against its documented code instead of only its prose.
+- `sb_store`'s `chrome` action and `sb_page_create` now re-read and re-store the page immediately after attaching a global section, so the platform's usage count and referencing-pages list reflect the attachment right away instead of only after a later save.
+
+## [0.62.0] - 2026-09-20
+
+### Added
+- `sb_api_call` can now reach a route the generated catalog does not carry at all, by passing `method` and `path` directly, under the same credential routing, `dry_run` default, and `SB_SITE` fallback as a catalogued call; a `method` + `path` that names a route the catalog already holds folds back onto that catalogued operation instead, matched segment-wise so a path spelled with literal ids (e.g. `/api/sites/abc123/menus/m1`) still resolves and gets its shape and `sb_undo` support.
+- `sb_api_call`'s `item_offset` argument pages through a list answer after the platform's own pagination, for the many listing operations that carry no pagination of their own.
+- `sb_api_find` now names the raw call form and the three router-only routes (`/api/permissions`, `/api/plans`, `/api/locales`) when a search matches nothing.
+- `sb_add`, `sb_set`, `sb_move`, `sb_remove`, `sb_duplicate`, `sb_bind`, and `sb_event` now take a `force` argument that overrides a "soft" guard — one that only asserts what the catalog believes a renderer does, which can be stale against a newer deployment — and returns the overridden message under `forced` instead of throwing; a "hard" guard protecting a platform invariant with no way back (band order, a composed stamp, ROOT, the overlay root, a move into a node's own subtree, `specials` with a state) still refuses regardless of `force`.
+- `sb_store` gained three actions: `menu` binds a menu node on the open page to the site's menu and resolves its links the way the editor does; `overlay_attach` puts a pop-up on the open page or points a `list-dataset` at a quick-view panel, then re-reads the page as the editor requires; `app` installs one of the platform's built-in apps and creates the scaffold pages it needs.
+
+### Changed
+- `sb_api_call`'s raw (uncatalogued) call form now states what it cannot offer — no call sheet, no body shape, no `sb_undo` — on the dry run as well as on a real send, since `dry_run` defaults to true and that is when most callers first meet it.
+- `sb_api_call` now refuses a `path` carrying a query string, a fragment, or a backslash, since a query belongs in the `query` argument and a backslash could otherwise redirect the request off this install's own API host.
+- The generated catalog was regenerated against the platform: 560 API operations (up from 531), 193 of 251 write operations now carrying a documented body shape (up from 179 of 238), including the three domain-action bodies (`menu`, `overlay_attach`, `app`) recovered by a new segment-arm reader.
+
+### Fixed
+- `sb_store`'s `menu` action now resolves a product link, keeps a listing panel's local id through a rebuild, and its dry-run plan names every step it would take.
+- `sb_store`'s `overlay_attach` action is now a no-op when the overlay is already attached, refuses attaching to a different site than the one the open page belongs to, and refuses a popup carrying `list_id` (which only means something for a quickview).
+- `sb_store`'s `menu` dry-run plan now goes out through the same redaction every other flow's plan does, instead of being built by hand.
+- A `force` argument no longer hints "pass force:true" on a tool whose schema does not accept one, and `force:true` with no `forced` array supplied no longer drops the override record silently.
+
 ## [0.61.1] - 2026-09-17
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,41 @@ 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.63.0] - 2026-09-21
+
+### Added
+- `sb_store` có thêm hai action `global_attach` và `global_detach` để đặt một header hoặc footer dùng chung đã tồn tại lên trang đang mở, hoặc gỡ nó ra, mà không cần tự tay viết stamp đã compose.
+- `sb_page_state` là một tool mới, báo cáo xem bản draft của editor, trang đã publish, và bản sao của session này có khớp nhau hay không, đồng thời liệt kê các điểm khôi phục thật sự (checkpoint autosave và version có nhãn) khi chúng không khớp.
+- `sb_publish` giờ báo cáo `id` của bản ghi đã publish, `publishedAt`, và version draft mà nó được biên dịch từ đó, đồng thời nhận tham số `verify` để lấy trang storefront trực tiếp và xác nhận origin có đang phục vụ đúng bản đó không.
+
+### Fixed
+- `sb_event` giờ ghi `<a href>` mà renderer thực sự đọc cùng lúc với một click điều hướng, vì `node.events` không bao giờ được đọc cho một click `go_to_url`/`open_page` đơn lẻ; mọi điều hướng được tạo trước bản sửa này render, lưu và publish thành một control không làm gì khi khách bấm vào.
+- `sb_review` không còn ném lỗi khi tài liệu của trang trỏ tới một node con mà nó không có; giờ báo cáo lỗi này dưới dạng `missing_node`.
+- `sb_review` báo cáo `dead_nav` cho một click điều hướng đến được tài liệu mà không có phép chiếu href của nó.
+- Kiểm tra chồng lấp của `sb_look` và việc khung hình theo `node_id` giờ nhận diện một overlay (như cart drawer) dựa trên cách nó thực sự render ngoài màn hình, chứ không chỉ dựa vào stamp compose, loại bỏ hàng chục phát hiện off-canvas giả trên mỗi trang và cho phép khung hình một drawer được tạo thẳng vào tài liệu trang.
+- Lỗi API do một tool ném ra giờ mang theo `code` lỗi và mã trạng thái HTTP của nền tảng trong message, để một lỗi như bị từ chối do sai thứ tự band có thể được đối chiếu với mã đã tài liệu hóa thay vì chỉ dựa vào câu chữ.
+- Action `chrome` của `sb_store` và `sb_page_create` giờ đọc lại và lưu lại trang ngay sau khi gắn một global section, để số lượt sử dụng và danh sách trang tham chiếu của nền tảng phản ánh việc gắn kết ngay lập tức thay vì chỉ sau một lần lưu sau đó.
+
+## [0.62.0] - 2026-09-20
+
+### Added
+- `sb_api_call` giờ có thể gọi tới một route mà catalog được sinh ra hoàn toàn không mang, bằng cách truyền thẳng `method` và `path`, dưới cùng quy tắc chọn credential theo path, mặc định `dry_run`, và fallback `SB_SITE` như một lệnh gọi có trong catalog; một `method` + `path` trỏ đến route mà catalog đã có thì được gập ngược lại thành chính operation đó, khớp theo từng đoạn path nên một path viết bằng id literal (ví dụ `/api/sites/abc123/menus/m1`) vẫn được nhận diện và có đầy đủ shape cùng hỗ trợ `sb_undo`.
+- Tham số `item_offset` của `sb_api_call` cho phép lật qua các item trong một danh sách trả về sau khi đã áp dụng phân trang của chính nền tảng, dành cho rất nhiều operation liệt kê vốn không có phân trang riêng.
+- `sb_api_find` giờ nêu tên dạng gọi thô và ba route chỉ tồn tại trên router (`/api/permissions`, `/api/plans`, `/api/locales`) khi một tìm kiếm không khớp gì cả.
+- `sb_add`, `sb_set`, `sb_move`, `sb_remove`, `sb_duplicate`, `sb_bind`, và `sb_event` giờ nhận tham số `force` để ghi đè một guard "mềm" — loại chỉ khẳng định điều mà catalog tin là renderer sẽ làm, có thể đã lỗi thời so với bản triển khai mới hơn — và trả về thông điệp bị ghi đè dưới `forced` thay vì ném lỗi; một guard "cứng" bảo vệ bất biến của nền tảng không có đường quay lại (thứ tự band, một stamp đã compose, ROOT, overlay root, di chuyển một node vào chính subtree của nó, `specials` kèm state) vẫn từ chối bất kể `force`.
+- `sb_store` có thêm ba action: `menu` gắn một node menu trên trang đang mở vào menu của site và resolve các liên kết của nó giống hệt editor; `overlay_attach` đặt một pop-up lên trang đang mở hoặc trỏ một `list-dataset` vào panel quick-view, sau đó đọc lại trang như editor bắt buộc phải làm; `app` cài một app dựng sẵn của nền tảng và tạo các trang scaffold mà nó cần.
+
+### Changed
+- Dạng gọi thô (chưa có trong catalog) của `sb_api_call` giờ nêu rõ những gì nó không thể cung cấp — không call sheet, không body shape, không `sb_undo` — ngay trên dry run chứ không chỉ khi gửi thật, vì `dry_run` mặc định là true và đó là lúc phần lớn người gọi gặp nó lần đầu.
+- `sb_api_call` giờ từ chối một `path` mang query string, fragment, hoặc dấu gạch chéo ngược, vì query thuộc về tham số `query`, còn dấu gạch chéo ngược có thể khiến request bị chuyển hướng khỏi host API của chính bản cài đặt này.
+- Catalog được sinh ra đã được làm mới dựa trên nền tảng: 560 operation API (tăng từ 531), 193 trong 251 lệnh ghi giờ mang hình dạng body đã được ghi lại (tăng từ 179 trong 238), bao gồm ba hình dạng body của domain-action (`menu`, `overlay_attach`, `app`) được khôi phục nhờ một bộ đọc segment-arm mới.
+
+### Fixed
+- Action `menu` của `sb_store` giờ resolve được liên kết sản phẩm, giữ nguyên id cục bộ của một panel listing qua một lần rebuild, và plan của dry run nêu tên đầy đủ từng bước sẽ thực hiện.
+- Action `overlay_attach` của `sb_store` giờ không làm gì khi overlay đã được gắn sẵn, từ chối gắn vào một site khác với site của trang đang mở, và từ chối một popup mang `list_id` (giá trị này chỉ có ý nghĩa với quickview).
+- Plan dry run của action `menu` trong `sb_store` giờ đi qua cùng bước redact như plan của mọi flow khác, thay vì được dựng tay.
+- Tham số `force` không còn gợi ý "pass force:true" trên một tool mà schema của nó không nhận tham số này, và `force:true` không kèm mảng `forced` không còn làm mất bản ghi ghi đè một cách âm thầm.
+
 ## [0.61.1] - 2026-09-17
 
 ### Added

package/README.md

@@ -83,7 +83,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_connect` | Log in, list the sites this account can operate, report which credentials are present |
 | `sb_site_list` | List the sites this account can operate |
 | `sb_api_find` | Find API operations by intent — one line per match — then read one operation's call sheet by id: real parameter schemas, the credential it needs, and the body's fields read off the handler that decodes them, each carrying the trap its own doc comment records |
-| `sb_api_call` | Execute one operation. Defaults to a dry run that sends nothing |
+| `sb_api_call` | Execute an operation, or any route by method+path; dry run by default. Field selection and local result pagination |
 | `sb_page_open` | Open a page for editing and return its outline |
 | `sb_outline` | The open page as a compressed tree — never a raw document dump |
 | `sb_node_read` | One node in full, with a warning if it is a shared global |
@@ -98,7 +98,8 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_template_use` | Instantiate a template into a page |
 | `sb_page_list` | Every page on the site |
 | `sb_page_create` | Create a page — a store type arrives with the editor's own starting document; `type` is the route for checkout, product, category, post, course |
-| `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
+| `sb_publish` | Compile the draft into the live page (cascades to shared globals), report which revision went live, and with `verify` check the origin is serving it |
+| `sb_page_state` | Which of a page's three copies is which — the DRAFT the editor canvas shows, the PUBLISHED row the storefront serves, and this session's — plus whether the editor will render the canvas BLANK, and where the recovery points are |
 | `sb_review` | Every defect a visitor would see, each with its fix, plus the five gaps between this store and a paid order |
 | `sb_media_list` | The site's media library |
 | `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from, one or several at a time |
@@ -109,10 +110,10 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_import` | Read a page from any public URL and add its structure and content to the open page as real elements, styled with THIS page's own tokens — a translation, not a clone |
 | `sb_import_site` | Read a WHOLE site from one URL — its sitemap, or the links on that page — and give each page found its own draft page here, built from this site's tokens; the entry page's own colours and type scale also patch into this SITE'S theme, so it stops being purely a read |
 | `sb_theme` | Read or patch the site's palette and type scale — the layer every style preset resolves from, so one token repaints every page |
-| `sb_store` | Run a store flow that must happen in a fixed order — the four writes that make a working checkout, or any of the platform's 17 form templates (login, register, forgot, contact, subscribe …) with its own field document |
+| `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer), `menu` (a menu node bound to the site's menu, its links resolved), `overlay_attach` (a pop-up or quick view on the open page) and `app` (a built-in app plus the pages it needs), `global_attach` / `global_detach` (put an EXISTING shared section on the open page, or take it off) |
 | `sb_undo` | Put back what a PUT replaced. The SECOND answer for a page, not the only one: the platform has versions, history and restore (`sb_api_find` "page versions"), which outlive this process — reach for those first and use this for every other shaped PUT |
 
-Twenty-eight tools, **531 API operations** (179 of the 238 writes carrying a body shape read
+Twenty-eight tools, **560 API operations** (193 of the 251 writes carrying a body shape read
 off the handler), 113 elements, 79 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything
 the platform can do stays reachable — and operations added to the platform arrive with the

package/README.vi.md

@@ -80,7 +80,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_connect` | Đăng nhập, liệt kê site tài khoản vận hành được, báo đang có credential nào |
 | `sb_site_list` | Liệt kê site tài khoản vận hành được |
 | `sb_api_find` | Tìm operation theo ý định — mỗi kết quả một dòng — rồi đọc call sheet của một operation theo id: schema tham số thật, credential cần dùng, và các trường body đọc thẳng từ handler decode chúng, mỗi trường mang theo cái bẫy doc comment của chính nó ghi lại |
-| `sb_api_call` | Chạy một operation. Mặc định chạy khô, không gửi gì |
+| `sb_api_call` | Chạy operation, hoặc bất kỳ route nào bằng method+path; mặc định chạy khô. Chọn field và phân trang kết quả phía MCP |
 | `sb_page_open` | Mở một trang để sửa và trả về outline |
 | `sb_outline` | Trang đang mở dạng cây nén — không bao giờ dump tài liệu thô |
 | `sb_node_read` | Một node đầy đủ, kèm cảnh báo nếu nó là global dùng chung |
@@ -95,7 +95,8 @@ nhét ngược lại vào mọi bản cài.
 | `sb_template_use` | Thả một template vào trang |
 | `sb_page_list` | Mọi trang của site |
 | `sb_page_create` | Tạo một trang — trang cửa hàng sinh ra đã có sẵn tài liệu như trong editor; `type` là đường đi cho checkout, product, category, post, course |
-| `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung) |
+| `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung), báo bản nào đã lên live, và với `verify` kiểm origin đã phục vụ đúng bản đó chưa |
+| `sb_page_state` | Ba bản sao của một trang, bản nào là bản nào — bản NHÁP canvas editor hiển thị, dòng PUBLISHED storefront phục vụ, và bản phiên này giữ — kèm dự báo editor có render canvas TRẮNG không, và các điểm phục hồi nằm ở đâu |
 | `sb_review` | Mọi khiếm khuyết người xem sẽ thấy, kèm lệnh sửa từng cái, và năm khoảng trống chắn giữa cửa hàng với một đơn đã thanh toán |
 | `sb_media_list` | Thư viện ảnh của site |
 | `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn, một hoặc nhiều tấm một lượt |
@@ -106,10 +107,10 @@ nhét ngược lại vào mọi bản cài.
 | `sb_import` | Đọc một trang từ URL công khai bất kỳ và thêm cấu trúc + nội dung của nó vào trang đang mở dưới dạng element thật, mang token của CHÍNH trang này — là dịch lại, không phải sao chép |
 | `sb_import_site` | Đọc CẢ website từ một URL — sitemap của nó, hoặc các link trên trang đó — và tạo cho mỗi trang tìm được một trang nháp riêng ở đây, dựng bằng token của site này; màu và thang chữ của trang gốc cũng được vá vào THEME của site này, nên đây không còn thuần là đọc |
 | `sb_theme` | Đọc hoặc vá bảng màu và thang chữ của site — tầng mà mọi style preset phân giải từ đó, nên một token thay áo cho mọi trang |
-| `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — bốn lệnh ghi tạo nên trang thanh toán, hoặc gieo bất kỳ template nào trong 17 form của nền tảng (login, register, forgot, contact, subscribe …) kèm field document của nó |
+| `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — `checkout` (bốn lệnh ghi tạo nên trang thanh toán), `form` (một trong 17 template của nền tảng kèm field document của nó), `chrome` (một header hoặc footer dùng chung), `menu` (một node menu bind vào menu của site, link đã phân giải), `overlay_attach` (một pop-up hay quick view trên trang đang mở) `app` (một app dựng sẵn kèm những trang nó cần), và `global_attach` / `global_detach` (đặt một section dùng chung ĐÃ CÓ lên trang đang mở, hoặc gỡ ra) |
 | `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè. Với TRANG thì đây là đường về thứ hai chứ không phải duy nhất: nền tảng có version, history và restore (`sb_api_find` "page versions"), và chúng sống lâu hơn tiến trình này — hãy dùng chúng trước, còn tool này cho mọi PUT có hình dạng khác |
 
-Hai mươi tám tool, **531 operation API** (179 trong 238 lệnh ghi có hình dạng body đọc thẳng
+Hai mươi tám tool, **560 operation API** (193 trong 251 lệnh ghi có hình dạng body đọc thẳng
 từ handler), 113 element, 79 nguồn binding. `sb_api_find` là
 một chỉ mục chứ không phải mỗi endpoint một tool, nên danh sách tool vẫn ngắn trong khi mọi
 thứ nền tảng làm được vẫn với tới — và operation mới thêm bên nền tảng sẽ tự có sau lần