sbuilder-mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,10 +1,48 @@
 # Changelog
 
-## 0.1.2 — 2026-08-29
+**English** · [Tiếng Việt](./CHANGELOG.vi.md)
 
-244625
+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.1.1 — 2026-08-28
+## [0.1.4] - 2026-09-07
+
+### Added
+- sb_set accepts an edits[] batch so many nodes save and publish in one call instead of one round trip per node.
+- sb_api_call shapes list answers with pick and max_items, and cuts an oversized list to fit the result cap while saying how many items were shown and how to narrow the call.
+- All 25 tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so compliant clients stop asking for confirmation on reads.
+- Trap 5 is now guarded in code: an edit inside an app block's interior is refused instead of being silently lost on save.
+- The catalog is regenerated from the platform: 106 elements, 412 API operations, and 26 binding sources.
+
+### Changed
+- sb_look keeps Chrome open across calls, launching it lazily and reusing it while connected, and captures multiple widths in parallel instead of one at a time.
+- sb_look screenshots are JPEG by default (format: "png" still available), which cuts image size and cost without changing token count.
+- sb_look's node_id boxes now count depth from the framed node and cover only its subtree.
+- sb_page_list, sb_templates and sb_media_list return a smaller, whitelisted set of fields instead of the whole document or settings blob.
+- sb_look's measured layout boxes are returned as compact tuples ([id, type, x, y, w, h]) instead of pretty-printed objects, with box_depth controlling how deep the tree goes.
+- Tool descriptions for sb_bind, sb_look, sb_live_join, sb_review and sb_api_find are shorter; sb_bind no longer interpolates all 26 binding sources into its schema.
+- The server's handshake instructions are shorter, take their tool/element/operation counts from generated source records, and no longer claim a base style value vanishes on publish.
+- Findings from sb_page_open, sb_review and sb_look reuse one fix template per kind of defect, and directives such as FIX THESE are said once per process instead of on every call.
+- Every tool result is now compact JSON.
+
+### Fixed
+- sb_live_join reports why an API key cannot join a live session instead of joining silently into a socket that never opens, since the platform refuses wbk_ keys.
+- Multipart uploads now surface the platform's per-field validation errors instead of a generic failure.
+- Duplicating a subtree that contains an app block is refused instead of being silently reduced.
+- fill() throws when a code has no template instead of returning an empty fix.
+- sb_api_call's publish step splits an ops batch to stay under the live socket's 4 MiB frame cap instead of risking a dropped connection.
+- A non-list answer's size is no longer silently cut, and asking for max_items on a non-list answer is now reported instead of ignored.
+- A platform response field named truncated is no longer overwritten by the result-shaping logic.
+- Each screenshot page now closes in its own finally block, so a tab lost to a first rejection can no longer leak for the life of the process.
+
+## [0.1.2] - 2026-08-29
+
+### Added
+- The server reports which machine and which client it runs on, so the store's Agent app can show every connected agent.
+- sb_look measures the render: content past the viewport, overlapping siblings, and text too small to read are reported with the width they happen at.
+
+## [0.1.1] - 2026-08-28
 
 - fix(release): ask for the one-time password instead of dying on it
 - feat: sb_media_upload — the agent can add images
@@ -49,7 +87,7 @@
 - feat: repo skeleton, response helpers, and a green build/test/smoke gate
 - docs: design spec and phase-1 implementation plan for @sbuilder/mcp
 
-## 0.1.0
+## [0.1.0]
 
 First release.
 

package/CHANGELOG.vi.md

@@ -0,0 +1,51 @@
+# Changelog
+
+[English](./CHANGELOG.md) · **Tiếng Việt**
+
+Mọi thay đổi đáng chú ý của dự án được ghi lại trong file này.
+Đị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.1.4] - 2026-09-07
+
+### Added
+- sb_set nhận một mảng edits[] để ghi nhiều node trong một lần gọi, thay vì lưu và publish riêng cho từng node.
+- sb_api_call định dạng lại kết quả dạng danh sách bằng pick và max_items, và cắt bớt danh sách quá lớn để vừa giới hạn kết quả, kèm thông báo đã hiển thị bao nhiêu mục và cách thu hẹp lời gọi.
+- Cả 25 tool đều mang chú thích MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), giúp các client tuân thủ chuẩn không còn hỏi xác nhận cho thao tác chỉ đọc.
+- Bẫy thứ 5 giờ được chặn bằng code: một chỉnh sửa bên trong app block bị từ chối thay vì âm thầm mất khi lưu.
+- Catalog được tạo lại từ nền tảng: 106 element, 412 API operation, và 26 nguồn binding.
+
+### Changed
+- sb_look giữ Chrome mở giữa các lần gọi, khởi chạy lười và tái sử dụng khi còn kết nối, đồng thời chụp nhiều chiều rộng song song thay vì lần lượt.
+- Ảnh chụp của sb_look mặc định là JPEG (vẫn có thể chọn format: "png"), giúp giảm dung lượng ảnh và chi phí mà không đổi số token.
+- Các box theo node_id của sb_look giờ tính độ sâu từ node được khung và chỉ bao phủ subtree của nó.
+- sb_page_list, sb_templates và sb_media_list trả về tập trường được lọc sẵn nhỏ hơn, thay vì cả document hay cả khối settings.
+- Các box đo layout của sb_look giờ trả về dạng tuple gọn ([id, type, x, y, w, h]) thay vì object in đẹp, với box_depth điều khiển độ sâu duyệt cây.
+- Mô tả của các tool sb_bind, sb_look, sb_live_join, sb_review và sb_api_find được rút gọn; sb_bind không còn chèn cả 26 nguồn binding vào schema.
+- Hướng dẫn bắt tay của server ngắn hơn, lấy số lượng tool/element/operation từ dữ liệu sinh tự động, và không còn nói sai rằng giá trị style ở base biến mất khi publish.
+- Các finding từ sb_page_open, sb_review và sb_look dùng chung một mẫu fix cho mỗi loại lỗi, và các chỉ dẫn như FIX THESE chỉ được nói một lần cho mỗi tiến trình thay vì lặp lại ở mọi lần gọi.
+- Mọi kết quả trả về của tool giờ là JSON rút gọn.
+
+### Fixed
+- sb_live_join báo rõ lý do một API key không thể tham gia phiên live, thay vì âm thầm tham gia vào một socket không bao giờ mở, vì nền tảng từ chối key dạng wbk_.
+- Upload dạng multipart giờ trả về đúng lỗi kiểm tra theo từng trường của nền tảng thay vì một lỗi chung chung.
+- Nhân bản một subtree chứa app block bị từ chối thay vì bị âm thầm rút gọn.
+- fill() báo lỗi khi một code không có template thay vì trả về một fix rỗng.
+- Bước publish của sb_api_call chia nhỏ batch ops để nằm dưới giới hạn khung 4 MiB của socket live, thay vì có nguy cơ làm rớt kết nối.
+- Kết quả không phải danh sách không còn bị cắt âm thầm, và việc dùng max_items trên một kết quả không phải danh sách giờ được báo thay vì bị bỏ qua.
+- Trường truncated do nền tảng trả về không còn bị logic định dạng kết quả ghi đè.
+- Mỗi trang chụp ảnh giờ đóng trong khối finally riêng, nên một tab bị lỗi lần đầu không còn rò rỉ suốt vòng đời tiến trình.
+
+## [0.1.2] - 2026-08-29
+
+### Added
+- Server báo cho nền tảng biết nó đang chạy trên máy nào và trong client nào, để app Agent của cửa hàng hiển thị được mọi agent đang kết nối.
+- sb_look đo kết quả render: nội dung tràn khỏi viewport, các phần tử anh em chồng lên nhau, và chữ quá nhỏ để đọc được báo cáo kèm chiều rộng mà lỗi xảy ra.
+
+## [0.1.1] - 2026-08-28
+
+Sửa lỗi, thêm tool, và vòng lặp nhìn.
+
+## [0.1.0]
+
+Bản phát hành đầu tiên.

package/README.md

@@ -63,13 +63,13 @@ 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 — returns real parameter schemas, the credential each 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 an explicit note when the platform's document fails to describe a request body |
 | `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 |
 | `sb_node_read` | One node in full, with a warning if it is a shared global |
 | `sb_catalog_search` | Find an element by what it should do, using the platform's own AI hints |
-| `sb_traits_for` | Which trait groups an element accepts, plus defaults and containment rules |
+| `sb_traits_for` | An element's inspector — tabs, groups, controls and what each declared one writes — plus its AI hints, defaults and containment rules |
 | `sb_add` | Add an element — or a whole nested subtree — in one call |
 | `sb_set` | Write style/config/specials. Per breakpoint by default |
 | `sb_move` | Move a node to another parent |
@@ -84,12 +84,17 @@ make, because those mean "this person's account".
 | `sb_media_list` | The site's media library |
 | `sb_media_upload` | Add an image and get its URL — the only route, the upload is multipart |
 | `sb_live_join` | Join the editor's live-edit room as a visible peer — edits then appear live |
-| `sb_look` | Save, render, and return screenshots plus measured node boxes |
+| `sb_look` | Save, render, and return screenshots plus measured node boxes and layout defects measured on the render |
 | `sb_bind` | Bind a node's content to real store data |
 
-Twenty-five tools, **310 API operations**. `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`.
+Twenty-five tools, **412 API operations**, 106 elements, 26 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`.
+
+Every result is compact JSON, every directive is said once per process, and every tool
+carries MCP annotations — a client that honours them stops asking a person to confirm a
+read.
 
 Full reference: [`docs/tools.md`](./docs/tools.md).
 
@@ -117,9 +122,27 @@ npm run smoke     # offline self-test; must print ALL GOOD
 Contributor guide: [`CLAUDE.md`](./CLAUDE.md). Design rationale:
 [`docs/superpowers/specs/`](./docs/superpowers/specs/).
 
+### Release
+
+A push to `main` that touches `src/**` releases on its own
+(`.github/workflows/auto-release.yml`): the gate runs (build, test, smoke), the version
+bump is read off the commit subject — `feat` is minor, `BREAKING CHANGE` or `!` is major,
+anything else is patch — Claude writes the changelog entry in both languages,
+`server.json` is synced, the release is committed as `chore(release): vX.Y.Z` and tagged,
+then published to npm, as a GitHub Release, and to the MCP Registry through GitHub OIDC.
+`workflow_dispatch` runs the same flow with a bump you choose. A commit whose subject
+contains `chore(release):` or `release: v` is skipped, so a release never triggers another.
+
+The workflow needs two repository secrets in the `prod` environment: `NPM_ACCESS_TOKEN`
+and `CLAUDE_CODE_OAUTH_TOKEN`. The registry step needs none.
+
+`npm run release` (`scripts/release.mjs`) is the offline path — a machine with no CI, or a
+release cut while a secret is being rotated. It runs the same gate and writes the same
+`## [x.y.z] - date` changelog heading, so the two never disagree.
+
 ## Designing safely
 
-Four platform rules fail **silently** if a client does not know them, so they are encoded
+Five platform rules fail **silently** if a client does not know them, so they are encoded
 here as tested code rather than advice:
 
 - **Band order** — ROOT's children must read `[header][middle][footer]`, or the platform
@@ -131,12 +154,15 @@ here as tested code rather than advice:
   publishing cascades. Any result touching one says so.
 - **Responsive by default** — `sb_set` writes per breakpoint, because a design should
   respond. Base is the cascade's fallback layer, not a trap.
+- **App blocks** — a marketplace app's subtree is composed onto the page on read and reduced
+  back to one reference node on save, so an edit inside it is lost without a word. Every
+  write refuses the interior; the outline flags the block root `app: true`.
 
 ## Status
 
 All three phases shipped: authentication and full API reach; the page document, patch
-protocol, builder and the four traps; the live-edit socket, the yield rule, and the vision
-loop.
+protocol, builder and the five traps; the live-edit socket, the yield rule, and the vision
+loop. Since then: a token diet across every result, and releases that cut themselves.
 
 Requires **Node ≥22** (the global `WebSocket`) and, for `sb_look` only, **system Google
 Chrome** — `playwright-core` bundles no browser, so installing downloads nothing.

package/README.vi.md

@@ -60,13 +60,13 @@ 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 — trả về 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ả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_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ô |
 | `sb_node_read` | Một node đầy đủ, kèm cảnh báo nếu nó là global dùng chung |
 | `sb_catalog_search` | Tìm element theo việc nó cần làm, dùng chính AI hints của nền tảng |
-| `sb_traits_for` | Element nhận nhóm trait nào, kèm default và luật chứa con |
+| `sb_traits_for` | Inspector của element — tab, nhóm, control và mỗi control khai báo sẵn ghi vào đâu — kèm AI hints, default và luật chứa con |
 | `sb_add` | Thêm một element — hoặc cả cây con lồng nhau — trong một lần gọi |
 | `sb_set` | Ghi style/config/specials. Mặc định theo breakpoint |
 | `sb_move` | Chuyển node sang cha khác |
@@ -81,12 +81,16 @@ là "tài khoản của người này".
 | `sb_media_list` | Thư viện ảnh của site |
 | `sb_media_upload` | Thêm ảnh và lấy URL — đường duy nhất, vì upload là multipart |
 | `sb_live_join` | Vào phòng live-edit của editor như một peer nhìn thấy được — sửa gì hiện ngay |
-| `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của từng node |
+| `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_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật |
 
-Hai mươi lăm tool, **310 operation API**. `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.
+Hai mươi lăm tool, **412 operation API**, 106 element, 26 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.
+
+Mọi kết quả đều là JSON nén, mọi directive chỉ nói một lần mỗi process, và mọi tool đều mang
+MCP annotation — client nào tôn trọng chúng sẽ thôi hỏi người dùng xác nhận một lần đọc.
 
 Tra cứu đầy đủ: [`docs/tools.vi.md`](./docs/tools.vi.md).
 
@@ -114,9 +118,27 @@ npm run smoke     # tự kiểm offline; phải in ALL GOOD
 Hướng dẫn đóng góp: [`CLAUDE.md`](./CLAUDE.md). Lý do thiết kế:
 [`docs/superpowers/specs/`](./docs/superpowers/specs/).
 
+### Phát hành
+
+Một lần push lên `main` có đụng `src/**` sẽ tự phát hành
+(`.github/workflows/auto-release.yml`): cổng kiểm chạy (build, test, smoke), mức tăng phiên
+bản đọc từ tiêu đề commit — `feat` là minor, `BREAKING CHANGE` hoặc `!` là major, còn lại là
+patch — Claude viết mục changelog bằng cả hai ngôn ngữ, `server.json` được đồng bộ, bản phát
+hành được commit là `chore(release): vX.Y.Z` và gắn tag, rồi publish lên npm, thành GitHub
+Release, và lên MCP Registry qua GitHub OIDC. `workflow_dispatch` chạy đúng luồng đó với mức
+tăng bạn chọn. Commit có tiêu đề chứa `chore(release):` hoặc `release: v` thì bị bỏ qua, nên
+một lần phát hành không bao giờ kích hoạt lần khác.
+
+Workflow cần hai secret của repo trong environment `prod`: `NPM_ACCESS_TOKEN` và
+`CLAUDE_CODE_OAUTH_TOKEN`. Bước registry không cần secret nào.
+
+`npm run release` (`scripts/release.mjs`) là đường offline — máy không có CI, hoặc phát hành
+đúng lúc đang xoay secret. Nó chạy cùng cổng kiểm và ghi cùng tiêu đề changelog
+`## [x.y.z] - date`, nên hai bên không bao giờ lệch nhau.
+
 ## Thiết kế an toàn
 
-Bốn luật của nền tảng hỏng **im lặng** nếu client không biết, nên chúng được viết thành code
+Năm luật của nền tảng hỏng **im lặng** nếu client không biết, nên chúng được viết thành code
 có test chứ không phải lời khuyên:
 
 - **Thứ tự băng** — con của ROOT phải đọc `[header][middle][footer]`, sai là nền tảng từ
@@ -127,11 +149,15 @@ có test chứ không phải lời khuyên:
   thì lan. Mọi kết quả đụng tới nó đều nói rõ.
 - **Mặc định responsive** — `sb_set` ghi theo breakpoint, vì một thiết kế nên đáp ứng. Base
   là lớp dự phòng của cascade, không phải cái bẫy.
+- **App block** — cây con của một app trên marketplace được ghép vào trang lúc đọc và thu về
+  một node tham chiếu lúc lưu, nên sửa gì bên trong là mất mà không một lời. Mọi lần ghi đều
+  từ chối phần bên trong; outline cắm cờ `app: true` cho gốc block.
 
 ## Trạng thái
 
 Cả ba giai đoạn đã xong: xác thực và với tới toàn bộ API; tài liệu trang, giao thức patch,
-builder và bốn cái bẫy; socket live-edit, luật nhường, và vòng lặp thị giác.
+builder và năm cái bẫy; socket live-edit, luật nhường, và vòng lặp thị giác. Sau đó: một đợt
+ăn kiêng token trên mọi kết quả, và phát hành tự cắt.
 
 Cần **Node ≥22** (WebSocket toàn cục) và, chỉ với `sb_look`, **Google Chrome của hệ thống** —
 `playwright-core` không kèm trình duyệt nào nên lúc cài không tải gì.