sbuilder-mcp 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ 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.5.0] - 2026-09-08
+
+### Added
+- sb_review reports default_seed_copy when a satellite's empty state still carries the platform's own English seed text, such as a repeater's empty state saying "No products yet", which previously matched no rule and reviewed clean.
+- sb_review reports form_fields_flush when a form, form-segment or form-step-nav stacks its fields with no gap between them, so each label reads as belonging to the control above it.
+- The install CLI accepts --site-name, matching the flag the platform's own Agent app install line already appends; it rides in as SB_SITE_NAME alongside the site id, and sb_connect reports it back so a session can display the store's name instead of its id.
+- A dry run of the install CLI now reports its own preview outcome and exit code instead of reusing the failure marker and exit code of a real install.
+- sb_api_call now falls back {siteId} and {siteID} path parameters to SB_SITE across all 289 operations that name the site, matching the fallback every other tool already applies through siteFor(); an explicit argument still wins.
+
+### Fixed
+- sb_set's state parameter now writes to the location the platform's cascade actually reads: node.states[state] at base, node.responsive[breakpoint].states[state] per breakpoint. Previously it wrote to a path nothing reads, and base:true combined with state:"hover" wrote the hover value straight into the plain style, leaving a node permanently styled as if hovered with no hover state at all.
+- sb_set now refuses a state argument on specials instead of silently dropping it, since content and identity do not vary by interaction state.
+- sb_review now walks into satellite nodes (a repeater's empty state, a variant option's skin, a quantity stepper's buttons, a menu or tab item's skin), so findings inside them are reported instead of being invisible to every check.
+- sb_review and sb_set now report a site-wide edit as such: a change to a node inside a global section's interior, or inside a site overlay like the cart drawer, is flagged rather than reading as an ordinary page-local edit.
+- sb_look now opens a closed overlay (such as the cart drawer) before measuring it, so a node_id resolving inside one can be photographed at all instead of failing with a clipping error that named neither the overlay nor the reason.
+- sb_look's preview_note no longer claims the draft preview renders every repeater's empty state; the draft preview threads real store data just like a published page, and the note now describes the real caveat, which is that an entity template previews with nothing bound.
+
+## [0.4.4] - 2026-09-08
+
+### Added
+- sb_api_find's call sheet now returns body_shape for 158 of the platform's 212 write operations, read directly off the Go handler that decodes each body instead of the 46 swagger.json describes, and expands one level of a nested struct (such as a product's variants, where the price actually lives) rather than stopping at the type name.
+- sb_store runs the four fixed-order writes a working checkout needs — create an order form, save it back whole with the cart as its source, fill in the store's real payment methods and delivery options, then create and publish a checkout-type page — since building them by hand and missing one step ships a Checkout button that answers 404. dry_run (the default) returns the ordered plan and the payment_methods/delivery_options the form will carry; executing returns form_id, page_id, slug and published.
+- sb_undo restores what a PUT made through sb_api_call just replaced, since the platform has no page history, versions or restore for pages, forms or settings; sb_api_call now reads a PUT's target through the matching GET before writing so there is something to put back.
+
+### Fixed
+- sb_review's checkoutPage gap now points to sb_store's checkout action instead of a fix that only creates a checkout-type page, which has no order form bound to the cart and takes no orders.
+- Redacting a request preview (used by sb_api_call and sb_undo) now matches platform-sourced credential field names such as accessKey, apiKey, clientSecret, hashSecret, webhookSecret, orderToken and signature, not just an exact "secret", since a body sb_undo echoes back comes from the platform's own vocabulary rather than a caller's.
+
 ## [0.4.3] - 2026-09-08
 
 ### Changed

package/CHANGELOG.vi.md

@@ -6,6 +6,34 @@ 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.5.0] - 2026-09-08
+
+### Added
+- sb_review giờ báo cáo default_seed_copy khi một node vệ tinh ở trạng thái rỗng vẫn còn mang seed text tiếng Anh của nền tảng, chẳng hạn trạng thái rỗng của một repeater ghi "No products yet" — trước đây không khớp với rule nào nên review vẫn báo sạch.
+- sb_review giờ báo cáo form_fields_flush khi một form, form-segment hoặc form-step-nav xếp các field mà không có gap, khiến mỗi label đọc như thể thuộc về control phía trên nó.
+- CLI cài đặt giờ nhận --site-name, khớp với flag mà dòng lệnh cài đặt của chính Agent app trên nền tảng đã thêm vào; giá trị này đi kèm dưới dạng SB_SITE_NAME cùng với site id, và sb_connect báo cáo lại giá trị này để một session có thể hiển thị tên cửa hàng thay vì id.
+- Một dry run của CLI cài đặt giờ báo cáo kết quả xem trước và exit code riêng, thay vì dùng chung dấu hiệu thất bại và exit code của một lần cài đặt thật.
+- sb_api_call giờ fallback các path parameter {siteId} và {siteID} về SB_SITE trên toàn bộ 289 operation có tên site, khớp với cách fallback mà mọi tool khác đã áp dụng qua siteFor(); một tham số được truyền rõ ràng vẫn được ưu tiên.
+
+### Fixed
+- Tham số state của sb_set giờ ghi đúng vào vị trí mà cascade của nền tảng thực sự đọc: node.states[state] ở base, node.responsive[breakpoint].states[state] theo từng breakpoint. Trước đây nó ghi vào một đường dẫn không ai đọc, và base:true kết hợp với state:"hover" ghi thẳng giá trị hover vào style thường, khiến node mang màu hover vĩnh viễn mà không hề có trạng thái hover.
+- sb_set giờ từ chối tham số state trên specials thay vì âm thầm bỏ qua, vì nội dung và identity không thay đổi theo trạng thái tương tác.
+- sb_review giờ đi vào cả các node vệ tinh (trạng thái rỗng của repeater, skin của một variant option, các nút của quantity stepper, skin của một mục menu hoặc tab), nên các finding bên trong chúng được báo cáo thay vì vô hình với mọi check.
+- sb_review và sb_set giờ báo cáo một chỉnh sửa có phạm vi toàn site đúng như bản chất của nó: thay đổi một node bên trong phần thân của một global section, hoặc bên trong một overlay của site như cart drawer, giờ được gắn cờ thay vì đọc như một chỉnh sửa cục bộ trên trang.
+- sb_look giờ mở một overlay đang đóng (như cart drawer) trước khi đo, nên một node_id nằm bên trong overlay đó giờ có thể được chụp ảnh, thay vì thất bại với lỗi clip không nêu rõ overlay hay lý do.
+- preview_note của sb_look không còn khẳng định rằng bản xem trước bản nháp render trạng thái rỗng của mọi repeater; bản xem trước bản nháp truyền dữ liệu cửa hàng thật giống như một trang đã publish, và ghi chú giờ mô tả đúng lưu ý thực sự — đó là một entity template xem trước sẽ không có gì được bind.
+
+## [0.4.4] - 2026-09-08
+
+### Added
+- sb_api_find giờ trả về body_shape cho 158 trong tổng số 212 write operation của nền tảng, đọc trực tiếp từ handler Go giải mã từng body thay vì chỉ 46 operation mà swagger.json mô tả, và mở rộng thêm một cấp cho struct lồng nhau (như variants của một sản phẩm, nơi giá thực sự nằm ở đó) thay vì dừng lại ở tên kiểu.
+- sb_store chạy bốn lượt ghi theo đúng thứ tự cố định mà một checkout hoạt động cần — tạo order form, lưu lại nguyên vẹn với giỏ hàng làm nguồn, điền các phương thức thanh toán và tùy chọn giao hàng thật của cửa hàng, rồi tạo và publish một trang kiểu checkout — vì tự dựng bằng tay mà bỏ sót một bước sẽ cho ra nút Checkout luôn trả về 404. dry_run (mặc định) trả về plan theo đúng thứ tự cùng payment_methods/delivery_options mà form sẽ mang; khi thực thi sẽ trả về form_id, page_id, slug và published.
+- sb_undo khôi phục lại thứ mà một PUT qua sb_api_call vừa ghi đè, vì nền tảng không có lịch sử, phiên bản hay khôi phục cho trang, form hay settings; sb_api_call giờ đọc đối tượng của một PUT qua GET tương ứng trước khi ghi, để có thứ mà khôi phục lại.
+
+### Fixed
+- Gap checkoutPage của sb_review giờ trỏ tới action checkout của sb_store thay vì một cách sửa chỉ tạo trang kiểu checkout, vốn không có order form gắn với giỏ hàng nên không nhận được đơn hàng nào.
+- Việc redact một bản xem trước request (dùng bởi sb_api_call và sb_undo) giờ khớp với các tên trường credential có nguồn gốc từ nền tảng như accessKey, apiKey, clientSecret, hashSecret, webhookSecret, orderToken và signature, chứ không chỉ khớp chính xác "secret", vì body mà sb_undo phản chiếu lại đến từ vocabulary của nền tảng chứ không phải của caller.
+
 ## [0.4.3] - 2026-09-08
 
 ### Changed

package/README.md

@@ -23,6 +23,11 @@ worse than one that does not exist.
 as `SB_SITE` and every tool then defaults to it. Without it the model has to carry the id
 through the session, which it can only get by listing pages and reading one back.
 
+`--site-name "Your Store"` rides alongside it as `SB_SITE_NAME`. It is a label, never an
+address — nothing resolves by it — but it lets the agent say the store's name back to you
+instead of a 32-character id you did not choose. The **Apps → AI agent** screen appends it
+whenever the store has a name.
+
 It **merges**: the servers already in those files stay, whatever it replaces is copied to
 `<file>.sbuilder-backup`, and a config it cannot parse is refused rather than overwritten —
 a file with a trailing comma is far likelier than one worth discarding, and it is what you
@@ -69,7 +74,7 @@ make, because those mean "this person's account".
 | --- | --- |
 | `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 an explicit note when the platform's document fails to describe a request body |
+| `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_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 |
@@ -93,8 +98,11 @@ make, because those mean "this person's account".
 | `sb_look` | Save, render, and return screenshots plus measured node boxes and layout defects measured on the render |
 | `sb_event` | Give a node a click action — open the cart, go to a page, open a pop-up |
 | `sb_bind` | Bind a node's content to real store data, or make a button add to the cart |
+| `sb_store` | Run a store flow that must happen in a fixed order — today, the four writes that make a working checkout |
+| `sb_undo` | Put back what a PUT replaced — the platform has no page history or restore, so this is the only way back |
 
-Twenty-five tools, **412 API operations**, 106 elements, 77 binding sources. `sb_api_find`
+Twenty-eight tools, **484 API operations** (158 of the 212 writes carrying a body shape read
+off the handler), 107 elements, 77 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
 next `npm run codegen`.

package/README.vi.md

@@ -23,6 +23,11 @@ còn tệ hơn một cờ không tồn tại.
 thành `SB_SITE` và mọi tool sau đó mặc định dùng site đó. Không có nó thì model phải mang
 theo id suốt phiên, mà cách duy nhất để lấy là liệt kê trang rồi đọc ngược ra.
 
+`--site-name "Tên Cửa Hàng"` đi kèm, được ghi thành `SB_SITE_NAME`. Nó là một nhãn, không phải
+địa chỉ — không có gì phân giải theo nó — nhưng nhờ nó agent gọi được tên cửa hàng thay vì
+đọc lại một id 32 ký tự bạn không đặt. Màn hình **Apps → AI agent** tự thêm nó khi cửa hàng
+có tên.
+
 Nó **gộp**: các server đã có trong file được giữ nguyên, thứ nó thay thế được chép sang
 `<file>.sbuilder-backup`, và một config nó không đọc được thì bị từ chối chứ không ghi đè —
 một file thừa dấu phẩy khả dĩ hơn nhiều một file đáng vứt, và đó chính là thứ bạn cần để sửa.
@@ -66,7 +71,7 @@ là "tài khoản của người này".
 | --- | --- |
 | `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ảnh báo rõ ràng khi tài liệu của nền tảng không mô tả request body |
+| `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_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ô |
@@ -90,8 +95,11 @@ là "tài khoản của người này".
 | `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của node và lỗi bố cục đo trên bản render |
 | `sb_event` | Gắn click action cho một node — mở giỏ, sang trang, mở pop-up |
 | `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật, hoặc biến một nút thành nút thêm vào giỏ |
+| `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — hiện là bốn lệnh ghi tạo nên một trang thanh toán hoạt động |
+| `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè — nền tảng không có lịch sử trang hay restore, nên đây là đường về duy nhất |
 
-Hai mươi lăm tool, **412 operation API**, 106 element, 77 nguồn binding. `sb_api_find` là
+Hai mươi tám tool, **484 operation API** (158 trong 212 lệnh ghi có hình dạng body đọc thẳng
+từ handler), 107 element, 77 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
 `npm run codegen` kế tiếp.

package/dist/catalog/api.generated.js

@@ -1,5 +1,5 @@
 export const SWAGGER_SOURCE = {
-    "operations": 481,
+    "operations": 484,
     "definitions": 99,
     "bodyCarrying": 171,
     "bodyUndescribed": 62,
@@ -10625,6 +10625,48 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/relation-slots",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/relation-slots",
+        "tags": [
+            "relations"
+        ],
+        "summary": "Curated relation slots and their picks",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/restore",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/restore",
+        "tags": [
+            "sites"
+        ],
+        "summary": "Restore a site from the trash",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/returns",
         "method": "GET",
@@ -12113,6 +12155,27 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "delete:/api/sites/{siteId}/trash",
+        "method": "DELETE",
+        "path": "/api/sites/{siteId}/trash",
+        "tags": [
+            "sites"
+        ],
+        "summary": "Permanently delete a site that is in the trash",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/webhooks",
         "method": "GET",