webcake-storefront-mcp 1.36.2 → 1.38.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -6
- package/README.vi.md +18 -6
- package/dist/auth/login.js +3 -2
- package/dist/builder/attributes.js +2 -2
- package/dist/builder/guide.js +3 -0
- package/dist/builder/native-first.js +168 -0
- package/dist/builder/page.js +69 -6
- package/dist/changelog.json +14 -14
- package/dist/guides.js +4 -1
- package/dist/index.js +1 -1
- package/dist/install.js +100 -52
- package/dist/server.js +2 -0
- package/dist/tools/builder.js +1 -1
- package/dist/tools/global-sources.js +41 -6
- package/dist/tools/images.js +4 -0
- package/dist/tools/pages.js +63 -24
- package/dist/tools/site-config.js +21 -1
- package/dist/web-guide-scene.js +611 -0
- package/dist/web-guide.js +13 -59
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -100,29 +100,42 @@ Pick **one**. Both hand your AI tool the full storefront toolkit. No coding.
|
|
|
100
100
|
|
|
101
101
|
### ① `npx` — runs on your machine (recommended)
|
|
102
102
|
|
|
103
|
-
Zero install, always the latest version, needs Node.js 18+. **One line** configures your
|
|
103
|
+
Zero install, always the latest version, needs Node.js 18+. **One line** connects your account and configures your AI apps:
|
|
104
104
|
|
|
105
105
|
```bash
|
|
106
|
-
#
|
|
106
|
+
# Opens the browser — click Connect, your installed IDEs are configured (prod)
|
|
107
107
|
npx -y webcake-storefront-mcp install
|
|
108
108
|
|
|
109
|
-
#
|
|
109
|
+
# Developers only — step by step: environment, login or token, IDE(s)
|
|
110
|
+
npx -y webcake-storefront-mcp install --dev
|
|
111
|
+
|
|
112
|
+
# Scripts and CI — every supported IDE, even ones not installed yet
|
|
110
113
|
npx -y webcake-storefront-mcp install --ide all --token <token> --session <session-id>
|
|
111
114
|
|
|
112
115
|
# Remove the server from every IDE config
|
|
113
116
|
npx -y webcake-storefront-mcp uninstall
|
|
114
117
|
```
|
|
115
118
|
|
|
116
|
-
|
|
119
|
+
**`install` asks nothing.** It connects to production, opens your browser so you can click *Connect*, then adds the server
|
|
120
|
+
to every AI app it finds on this computer. Your other servers are kept, and any config file it changes is backed up next to
|
|
121
|
+
the original as `<file>.webcake-storefront-backup`. No AI app found? It says so and exits with an error: install one and run it again,
|
|
122
|
+
or name it with `--ide`.
|
|
123
|
+
|
|
124
|
+
Need staging or local? `--dev` opens the step-by-step wizard, or skip it with `--env staging` / `--env local`.
|
|
125
|
+
|
|
126
|
+
> **Installed with an older version?** Run `install` again. Older versions wrote VS Code's config under the wrong key, so the
|
|
127
|
+
> server never appeared there, and registered Claude Code for the current folder only.
|
|
128
|
+
|
|
129
|
+
Targets for `--ide`: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `vscode`, `codex`, `antigravity`, `gemini`, `cline`, `kiro`, `opencode`, or `all`.
|
|
117
130
|
Just want to run the server (configure by hand)? `npx -y webcake-storefront-mcp`.
|
|
118
131
|
|
|
119
|
-
### ②
|
|
132
|
+
### ② Reconnect your account — no token copy/paste
|
|
120
133
|
|
|
121
134
|
```bash
|
|
122
135
|
npx -y webcake-storefront-mcp login
|
|
123
136
|
```
|
|
124
137
|
|
|
125
|
-
|
|
138
|
+
`install` already does this the first time. Use `login` when your token expires: it opens the builder's **connect page**, you click *Connect*, and your token + session are saved locally and picked up automatically.
|
|
126
139
|
|
|
127
140
|
### Remote URL — self-hosted, nothing per-client to install
|
|
128
141
|
|
package/README.vi.md
CHANGED
|
@@ -100,29 +100,41 @@ Chọn **một**. Cả hai đều trao cho AI toàn bộ bộ công cụ storefr
|
|
|
100
100
|
|
|
101
101
|
### ① `npx` — chạy trên máy bạn (khuyên dùng)
|
|
102
102
|
|
|
103
|
-
Không cần cài, luôn mới nhất, cần Node.js 18+. **Một dòng** cấu hình
|
|
103
|
+
Không cần cài, luôn mới nhất, cần Node.js 18+. **Một dòng** kết nối tài khoản và cấu hình các ứng dụng AI:
|
|
104
104
|
|
|
105
105
|
```bash
|
|
106
|
-
#
|
|
106
|
+
# Mở trình duyệt — bấm Kết nối, các IDE trên máy được cấu hình tự động (prod)
|
|
107
107
|
npx -y webcake-storefront-mcp install
|
|
108
108
|
|
|
109
|
-
#
|
|
109
|
+
# Chỉ dành cho dev — từng bước: môi trường, đăng nhập hoặc token, IDE
|
|
110
|
+
npx -y webcake-storefront-mcp install --dev
|
|
111
|
+
|
|
112
|
+
# Script và CI — mọi IDE được hỗ trợ, kể cả IDE chưa cài
|
|
110
113
|
npx -y webcake-storefront-mcp install --ide all --token <token> --session <session-id>
|
|
111
114
|
|
|
112
115
|
# Gỡ khỏi mọi IDE
|
|
113
116
|
npx -y webcake-storefront-mcp uninstall
|
|
114
117
|
```
|
|
115
118
|
|
|
116
|
-
|
|
119
|
+
**`install` không hỏi gì cả.** Lệnh kết nối tới production, mở trình duyệt để bạn bấm *Kết nối*, rồi thêm server vào mọi ứng dụng AI
|
|
120
|
+
tìm thấy trên máy. Các server khác của bạn được giữ nguyên, và file cấu hình nào bị đổi đều có bản sao lưu ngay cạnh, tên
|
|
121
|
+
`<file>.webcake-storefront-backup`. Không tìm thấy ứng dụng AI nào? Lệnh báo rõ và thoát với lỗi: hãy cài một ứng dụng rồi chạy lại, hoặc chỉ định bằng `--ide`.
|
|
122
|
+
|
|
123
|
+
Cần staging hoặc local? `--dev` mở các bước hỏi lần lượt, hoặc bỏ qua bằng `--env staging` / `--env local`.
|
|
124
|
+
|
|
125
|
+
> **Đã cài bằng bản cũ?** Hãy chạy lại `install`. Bản cũ ghi cấu hình VS Code sai khóa nên server không hiện trong VS Code, và chỉ đăng ký
|
|
126
|
+
> Claude Code cho đúng thư mục lúc chạy lệnh.
|
|
127
|
+
|
|
128
|
+
Giá trị cho `--ide`: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `vscode`, `codex`, `antigravity`, `gemini`, `cline`, `kiro`, `opencode`, hoặc `all`.
|
|
117
129
|
Chỉ muốn chạy server (cấu hình tay)? `npx -y webcake-storefront-mcp`.
|
|
118
130
|
|
|
119
|
-
### ②
|
|
131
|
+
### ② Kết nối lại tài khoản — khỏi copy token
|
|
120
132
|
|
|
121
133
|
```bash
|
|
122
134
|
npx -y webcake-storefront-mcp login
|
|
123
135
|
```
|
|
124
136
|
|
|
125
|
-
|
|
137
|
+
`install` đã làm việc này ở lần đầu. Dùng `login` khi token hết hạn: lệnh mở **trang kết nối** của builder, bấm *Kết nối* là token + session được lưu cục bộ và tự nạp.
|
|
126
138
|
|
|
127
139
|
### Remote URL — tự host, mỗi client khỏi cài gì
|
|
128
140
|
|
package/dist/auth/login.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
import { createServer } from "node:http";
|
|
5
5
|
import { randomBytes } from "node:crypto";
|
|
6
6
|
import { spawn, execFile } from "node:child_process";
|
|
7
|
-
import { resolveSettings } from "../config.js";
|
|
7
|
+
import { DEFAULT_ENV, resolveSettings } from "../config.js";
|
|
8
8
|
import { setConfig } from "../db.js";
|
|
9
9
|
function parseArgs(argv) {
|
|
10
10
|
const opts = { open: true };
|
|
@@ -132,7 +132,8 @@ function pathOf(url) {
|
|
|
132
132
|
}
|
|
133
133
|
export async function runLogin(argv) {
|
|
134
134
|
const opts = parseArgs(argv);
|
|
135
|
-
|
|
135
|
+
// Pin the env: a stale saved api_url (an old staging login) must not pair with the prod connect page.
|
|
136
|
+
const settings = resolveSettings({ env: process.env.WEBCAKE_ENV || DEFAULT_ENV, apiUrl: opts.apiUrl, appUrl: opts.appUrl });
|
|
136
137
|
const appUrl = settings.appUrl.replace(/\/$/, "");
|
|
137
138
|
const apiUrl = settings.apiUrl.replace(/\/$/, "");
|
|
138
139
|
const state = randomBytes(16).toString("hex");
|
|
@@ -18,8 +18,8 @@ catch {
|
|
|
18
18
|
const NOISE_KEYS = new Set(["undefined", "locked", "loaded", "isChangeSection"]);
|
|
19
19
|
// Cross-cutting specials available on virtually every element.
|
|
20
20
|
export const SHARED_SPECIALS = {
|
|
21
|
-
custom_class: "CSS class(es) on the element —
|
|
22
|
-
custom_css: "Raw CSS scoped to this element.",
|
|
21
|
+
custom_class: "CSS class(es) on the element — a hook for a few lines of site CSS, or for CMS glue code to write into it. Try style/config first.",
|
|
22
|
+
custom_css: "Raw CSS scoped to this element. Last resort: try runtime.style/config first (see NATIVE FIRST).",
|
|
23
23
|
element_async: "Mark the element async/lazy (advanced — usually leave unset).",
|
|
24
24
|
event_name_custom: "Custom analytics event name fired on interaction.",
|
|
25
25
|
tabIndex: "Bind this element to a tab item (TAB-ITEM-…) so a tabs element shows/hides it.",
|
package/dist/builder/guide.js
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
// Generation guide injected into builder tools so an AI agent understands the BuilderX
|
|
2
2
|
// page model well enough to author pages that actually render.
|
|
3
|
+
import { NATIVE_FIRST_GUIDE } from "./native-first.js";
|
|
3
4
|
export const BUILD_GUIDE = `# BuilderX page authoring guide
|
|
4
5
|
|
|
6
|
+
${NATIVE_FIRST_GUIDE}
|
|
7
|
+
|
|
5
8
|
## DESIGN SYSTEM — lock this FIRST, every build (this is what makes free composition look DESIGNED)
|
|
6
9
|
There are NO page templates here and NO seeded data — you COMPOSE every page from elements
|
|
7
10
|
based on the user's actual goal. (One optional shortcut: a single section may start from the
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
// Native-first policy. Pages are meant to be edited by dragging elements on the BuilderX canvas;
|
|
2
|
+
// UI written in custom code doesn't exist on that canvas, so the shop owner can't touch it and
|
|
3
|
+
// every visit pays for it. This module holds what an AI must try before code (taught by the build
|
|
4
|
+
// guide, the custom-code guide and the block messages) and the checks every code writer goes through.
|
|
5
|
+
/** Everyday storefront needs → the catalog elements that already do them. test/native-first keeps
|
|
6
|
+
* every name here honest against the catalog. */
|
|
7
|
+
export const NATIVE_ALTERNATIVES = [
|
|
8
|
+
{ need: "Banners, text, images, cards, sections", elements: ["section", "container", "text", "image", "button", "rectangle"] },
|
|
9
|
+
{ need: "Header, footer, menus", elements: ["menu", "member-bar", "dropdown"], note: "save as a global section" },
|
|
10
|
+
{ need: "Product lists, category tiles", elements: ["grid-product", "slider-product", "grid-category", "slider-category"] },
|
|
11
|
+
{ need: "Category filters and sorting", elements: ["checkbox-group", "color-group", "two-point-range", "radio-group", "tags", "dropdown"], note: "specials.filter_elements drives the grid" },
|
|
12
|
+
{ need: "Product detail", elements: ["product-gallery", "product-image-carousel", "attr", "quantity-input", "product-review", "masonry-review"] },
|
|
13
|
+
{ need: "Cart, including a slide-out cart", elements: ["cart-icon", "cart-items", "cart-droppable", "cart-items-empty", "bonus-items"] },
|
|
14
|
+
{ need: "Checkout", elements: ["form", "address", "payment", "delivery-method", "order-items", "coupon"], note: "form.specials.type = form_order" },
|
|
15
|
+
{ need: "Login, signup, account", elements: ["form", "member-bar", "order-history", "customer-address", "reward-point"], note: "form_login / form_signup / order_tracking" },
|
|
16
|
+
{ need: "Wishlist", elements: ["favorite-icon", "wishlist", "wishlist-container", "wishlist-item", "wishlist-empty"] },
|
|
17
|
+
{ need: "Search", elements: ["search-form", "search-droppable", "input-search"] },
|
|
18
|
+
{ need: "Promotions, flash sale, countdown", elements: ["flash-sale", "countdown", "promotions", "promotions-short", "coupon", "lucky-wheel"] },
|
|
19
|
+
{ need: "Sliders, tabs, accordions, galleries", elements: ["swiper", "carousel", "tabs", "collapse", "gallery"] },
|
|
20
|
+
{ need: "Popups, size charts", elements: ["popup", "table"], note: "open with an open_popup event" },
|
|
21
|
+
{ need: "Video, maps", elements: ["video", "googlemap"] },
|
|
22
|
+
{ need: "Blog", elements: ["post-list", "slider-post", "grid-blog"] },
|
|
23
|
+
];
|
|
24
|
+
export const SITE_CODE_FIELDS = ["code_before_head", "code_before_body", "code_custom_javascript", "code_custom_css"];
|
|
25
|
+
const SCRIPT_FIELDS = ["code_before_head", "code_before_body", "code_custom_javascript"];
|
|
26
|
+
const CSS_FIELDS = ["code_custom_css"];
|
|
27
|
+
/** Site-wide, in chars. Above `soft` a write must name its native gap; crossing `hard` is refused. */
|
|
28
|
+
export const CODE_BUDGET = {
|
|
29
|
+
script: { soft: 30_000, hard: 100_000 },
|
|
30
|
+
css: { soft: 20_000, hard: 50_000 },
|
|
31
|
+
};
|
|
32
|
+
/** custom_css + embed code across one page or global source. */
|
|
33
|
+
export const NODE_CODE_BUDGET = { soft: 10_000, hard: 30_000 };
|
|
34
|
+
/** Growth still allowed on a site already past the ceiling, so it can ship fixes while it migrates. */
|
|
35
|
+
const SMALL_FIX = 2_000;
|
|
36
|
+
export const NATIVE_FIRST_GUIDE = `## NATIVE FIRST — elements on the canvas before any code
|
|
37
|
+
Pages are edited by dragging elements on the canvas. UI written in code is not on that canvas: the
|
|
38
|
+
shop owner can't edit it, it is missing from the page HTML until scripts run, and it loads on every
|
|
39
|
+
page. Go down this list and stop at the FIRST step that works:
|
|
40
|
+
1. A NATIVE ELEMENT — list_elements / get_element (table below).
|
|
41
|
+
2. THE ELEMENT'S OWN SETTINGS — runtime.style/config, responsive overrides, events (hover, click,
|
|
42
|
+
open_popup, filter…), bindings (live product/cart/order/post data), runtime.config.animation,
|
|
43
|
+
position:"sticky"/"pinned". Most "this needs CSS/JS" ideas stop here.
|
|
44
|
+
3. AN EXISTING APP — list_apps / install_app (product_review, appointment, affiliates, course, automation…).
|
|
45
|
+
4. ONLY for a feature none of the above can do (a size advisor, mix & match, a custom quiz…) —
|
|
46
|
+
custom code COMBINED WITH THE CMS APP, so it stays small:
|
|
47
|
+
a. install_app "cms".
|
|
48
|
+
b. DATA goes in a collection (create_collection), never hard-coded in a script.
|
|
49
|
+
c. LOGIC goes in an HTTP function (edit_http_function action "add" + webcake-data, test with run_function).
|
|
50
|
+
d. UI stays NATIVE elements, marked with specials.custom_class.
|
|
51
|
+
e. Custom code is only the glue: load webcake-fn once in code_before_head
|
|
52
|
+
(<script src="https://cdn.jsdelivr.net/npm/webcake-fn/dist/webcake-fn.umd.min.js"></script>),
|
|
53
|
+
then read through it and write into those native elements:
|
|
54
|
+
api.get_SizeAdvice({ height }).then((r) => {
|
|
55
|
+
document.querySelector(".size-result p").textContent = r.size;
|
|
56
|
+
});
|
|
57
|
+
5. Third-party snippets (tracking, chat, a widget): the smallest code_before_head / embed that works.
|
|
58
|
+
A visual detail no style property can do: a few lines of CSS on a custom_class.
|
|
59
|
+
|
|
60
|
+
Never: render a page, section, product card, cart or checkout from JavaScript; put placeholder JSON in
|
|
61
|
+
text elements for a script to fill; copy product data into code (use products + bindings); or capture a
|
|
62
|
+
design as HTML. A reference design (Stitch, Figma, canvas, another site) is a visual brief: rebuild it
|
|
63
|
+
with elements (ingest_html → new_section) and accept small differences. If a design can't be matched
|
|
64
|
+
natively, tell the user what differs instead of switching to code.
|
|
65
|
+
|
|
66
|
+
Which element for which need:
|
|
67
|
+
${NATIVE_ALTERNATIVES.map((a) => `- ${a.need}: ${a.elements.join(", ")}${a.note ? ` (${a.note})` : ""}`).join("\n")}
|
|
68
|
+
|
|
69
|
+
Limits: site scripts ${CODE_BUDGET.script.soft / 1000}k chars, site CSS ${CODE_BUDGET.css.soft / 1000}k chars. Above that, a write is refused unless
|
|
70
|
+
it names the gap in native_gap (scripts ${CODE_BUDGET.script.hard / 1000}k / CSS ${CODE_BUDGET.css.hard / 1000}k is refused outright; a site already past that may only
|
|
71
|
+
remove code or add small fixes). validate_page also refuses new placeholder JSON in text and more than
|
|
72
|
+
${NODE_CODE_BUDGET.hard / 1000}k chars of custom_css + embed code on one page. Content already on a page never blocks an unrelated save.`;
|
|
73
|
+
const SMELLS = [
|
|
74
|
+
{
|
|
75
|
+
kind: "script",
|
|
76
|
+
limit: 20,
|
|
77
|
+
re: /<(?:div|section|article|ul|li|table|img|a|h[1-6]|p|button|form|input|span)[\s>]/gi,
|
|
78
|
+
label: "HTML tags in scripts",
|
|
79
|
+
fix: "build this UI with native elements",
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
kind: "script",
|
|
83
|
+
limit: 15,
|
|
84
|
+
re: /\.innerHTML\b|insertAdjacentHTML|createElement\(/g,
|
|
85
|
+
label: "DOM-building calls",
|
|
86
|
+
fix: "scripts should write into native elements, not create the UI",
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
kind: "script",
|
|
90
|
+
limit: 200,
|
|
91
|
+
re: /"[\w-]+"\s*:/g,
|
|
92
|
+
label: "JSON keys in scripts",
|
|
93
|
+
fix: "move this data to products + bindings or a CMS collection",
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
kind: "script",
|
|
97
|
+
limit: 0,
|
|
98
|
+
re: /<!doctype\s|<html[\s>]|<body[\s>]/gi,
|
|
99
|
+
label: "HTML document tags in scripts",
|
|
100
|
+
fix: "rebuild that page from native elements",
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
kind: "css",
|
|
104
|
+
limit: 30,
|
|
105
|
+
re: /!important/g,
|
|
106
|
+
label: "!important rules",
|
|
107
|
+
fix: "set runtime.style/config on the elements instead of overriding them",
|
|
108
|
+
},
|
|
109
|
+
];
|
|
110
|
+
const PASTED_DOCUMENT = /^\s*(?:<!doctype\s|<html[\s>])/i;
|
|
111
|
+
const joined = (values, fields) => fields.map((f) => String(values[f] || "")).filter(Boolean).join("\n");
|
|
112
|
+
// HTML comments don't count: snippets ship with notes like "paste after the opening <body> tag".
|
|
113
|
+
const count = (text, re) => (text.replace(/<!--[\s\S]*?-->/g, "").match(re) || []).length;
|
|
114
|
+
/** How much of the budget a site's code uses (for reads, so an agent sees it before writing). */
|
|
115
|
+
export function codeUsage(values) {
|
|
116
|
+
const script = joined(values, SCRIPT_FIELDS).length;
|
|
117
|
+
const css = joined(values, CSS_FIELDS).length;
|
|
118
|
+
return {
|
|
119
|
+
script: { used: script, budget: CODE_BUDGET.script.soft },
|
|
120
|
+
css: { used: css, budget: CODE_BUDGET.css.soft },
|
|
121
|
+
over_budget: script > CODE_BUDGET.script.soft || css > CODE_BUDGET.css.soft,
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
/** Judge a write by what it ADDS: shrinking or swapping code on an already-large site always passes,
|
|
125
|
+
* so a site can move off custom code step by step and still ship small fixes. */
|
|
126
|
+
export function checkSiteCode(before, changes) {
|
|
127
|
+
const after = { ...before, ...changes };
|
|
128
|
+
const hard = [];
|
|
129
|
+
const soft = [];
|
|
130
|
+
const texts = (kind) => {
|
|
131
|
+
const fields = kind === "script" ? SCRIPT_FIELDS : CSS_FIELDS;
|
|
132
|
+
return { old: joined(before, fields), now: joined(after, fields) };
|
|
133
|
+
};
|
|
134
|
+
for (const kind of ["script", "css"]) {
|
|
135
|
+
const { old, now } = texts(kind);
|
|
136
|
+
if (now.length <= old.length)
|
|
137
|
+
continue;
|
|
138
|
+
const { soft: softLimit, hard: hardLimit } = CODE_BUDGET[kind];
|
|
139
|
+
if (now.length > hardLimit && (old.length <= hardLimit || now.length - old.length > SMALL_FIX))
|
|
140
|
+
hard.push(`Site ${kind} would reach ${now.length} chars (ceiling ${hardLimit}). That is an app, not a snippet: move UI to native elements, data to a collection, logic to an HTTP function.`);
|
|
141
|
+
else if (now.length > softLimit)
|
|
142
|
+
soft.push(`Site ${kind} would reach ${now.length} chars (budget ${softLimit}).`);
|
|
143
|
+
}
|
|
144
|
+
for (const [field, value] of Object.entries(changes)) {
|
|
145
|
+
if (PASTED_DOCUMENT.test(String(value || "")) && !PASTED_DOCUMENT.test(String(before[field] || "")))
|
|
146
|
+
hard.push(`${field} is a whole HTML page. Rebuild it from native elements (ingest_html → new_section).`);
|
|
147
|
+
}
|
|
148
|
+
for (const s of SMELLS) {
|
|
149
|
+
const { old, now } = texts(s.kind);
|
|
150
|
+
const found = count(now, s.re);
|
|
151
|
+
if (found > s.limit && found > count(old, s.re))
|
|
152
|
+
soft.push(`${found} ${s.label} (limit ${s.limit}): ${s.fix}.`);
|
|
153
|
+
}
|
|
154
|
+
return { hard, soft };
|
|
155
|
+
}
|
|
156
|
+
/** Turn a check into the tool's refusal, or null when the write may proceed. */
|
|
157
|
+
export function codeGuard(check, nativeGap) {
|
|
158
|
+
if (check.hard.length)
|
|
159
|
+
return { error: "BLOCKED: custom code refused. Not saved.", reasons: check.hard, native_first: NATIVE_FIRST_GUIDE };
|
|
160
|
+
if (check.soft.length && !nativeGap)
|
|
161
|
+
return {
|
|
162
|
+
error: "BLOCKED: this looks like UI or data that belongs in native elements or the CMS. Not saved.",
|
|
163
|
+
reasons: check.soft,
|
|
164
|
+
native_first: NATIVE_FIRST_GUIDE,
|
|
165
|
+
if_truly_no_native_way: "Tell the user why, then call again with native_gap: the need, the elements/apps you checked, and what each one lacks.",
|
|
166
|
+
};
|
|
167
|
+
return null;
|
|
168
|
+
}
|
package/dist/builder/page.js
CHANGED
|
@@ -8,6 +8,7 @@ import { buildElement, isKnownType, ELEMENT_TYPES } from "./catalog.js";
|
|
|
8
8
|
import { randomString } from "./factory.js";
|
|
9
9
|
import { validateEvents } from "./events.js";
|
|
10
10
|
import { validateBindings } from "./bindings.js";
|
|
11
|
+
import { NODE_CODE_BUDGET } from "./native-first.js";
|
|
11
12
|
import { BREAKPOINTS, BREAKPOINT_KEYS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
|
|
12
13
|
const clone = (o) => structuredClone(o);
|
|
13
14
|
/** Parse a CSS px length ("52px") or a bare number (52) → number, else null. */
|
|
@@ -308,9 +309,11 @@ export function checkEmbeds(source) {
|
|
|
308
309
|
const errors = [];
|
|
309
310
|
const warnings = [];
|
|
310
311
|
walk(source, (node) => {
|
|
311
|
-
|
|
312
|
+
// googlemap counts too: the renderer inlines its specials.iframe as raw HTML.
|
|
313
|
+
if (node.type !== "embed" && node.type !== "googlemap")
|
|
312
314
|
return;
|
|
313
|
-
const
|
|
315
|
+
const s = node.specials || {};
|
|
316
|
+
const code = String(s.htmlCode || "") + String(s.iframe || "");
|
|
314
317
|
if (/<!doctype\s|<html[\s>]|<body[\s>]/i.test(code)) {
|
|
315
318
|
errors.push(`Embed "${node.id}" holds a whole HTML document (${code.length} chars). Embed is a last resort: build natively everything ` +
|
|
316
319
|
`native elements can (text/image/button/form/container… via ingest_html → new_section), and embed ONLY the one piece no element ` +
|
|
@@ -325,7 +328,67 @@ export function checkEmbeds(source) {
|
|
|
325
328
|
});
|
|
326
329
|
return { errors, warnings };
|
|
327
330
|
}
|
|
328
|
-
|
|
331
|
+
/** A text element holding only a JSON object is a slot for a script to fill, not content: that's how
|
|
332
|
+
* a page ends up empty on the canvas with its real UI in custom code. */
|
|
333
|
+
const isDataPlaceholder = (text) => {
|
|
334
|
+
const plain = text.replace(/<[^>]+>/g, "").replace(/"|�*34;|�*22;/gi, '"').trim();
|
|
335
|
+
if (!/^[{[]/.test(plain))
|
|
336
|
+
return false;
|
|
337
|
+
try {
|
|
338
|
+
const value = JSON.parse(plain);
|
|
339
|
+
const first = Array.isArray(value) ? value[0] : value;
|
|
340
|
+
return !!first && typeof first === "object" && Object.keys(first).length > 0;
|
|
341
|
+
}
|
|
342
|
+
catch {
|
|
343
|
+
return false;
|
|
344
|
+
}
|
|
345
|
+
};
|
|
346
|
+
function scanCode(source) {
|
|
347
|
+
const { errors, warnings } = checkEmbeds(source);
|
|
348
|
+
let code = 0;
|
|
349
|
+
walk(source, (node) => {
|
|
350
|
+
const s = node.specials || {};
|
|
351
|
+
code += String(s.custom_css || "").length + String(s.htmlCode || "").length + String(s.iframe || "").length;
|
|
352
|
+
if (typeof s.text === "string" && isDataPlaceholder(s.text))
|
|
353
|
+
errors.push(`"${node.id}" holds placeholder JSON for a script to fill (${s.text.slice(0, 60)}). Put the real content in native elements. See get_build_guide → NATIVE FIRST. If visitors should really read this JSON, add words around it.`);
|
|
354
|
+
});
|
|
355
|
+
return { errors, warnings, code };
|
|
356
|
+
}
|
|
357
|
+
const codeVolumeError = (code) => `${code} chars of custom_css + embed code (limit ${NODE_CODE_BUDGET.hard}). Build this with native elements. See get_build_guide → NATIVE FIRST.`;
|
|
358
|
+
/** Everything validatePage refuses about code inside a source: embeds, placeholders, code volume.
|
|
359
|
+
* Pass the `previous` source when saving over one: only what this save ADDS is refused, so an old
|
|
360
|
+
* page can still be edited and moved to native elements section by section. */
|
|
361
|
+
export function checkNativeContent(source, previous) {
|
|
362
|
+
const { errors, warnings, code } = scanCode(source);
|
|
363
|
+
const old = previous ? scanCode(previous) : null;
|
|
364
|
+
const added = old ? errors.filter((e) => !old.errors.includes(e)) : errors;
|
|
365
|
+
if (code > NODE_CODE_BUDGET.hard && (!old || code > old.code))
|
|
366
|
+
added.push(codeVolumeError(code));
|
|
367
|
+
else if (code > NODE_CODE_BUDGET.soft)
|
|
368
|
+
warnings.push(`${code} chars of custom_css + embed code (budget ${NODE_CODE_BUDGET.soft}): check whether native elements or their settings can replace it.`);
|
|
369
|
+
return { errors: added, warnings };
|
|
370
|
+
}
|
|
371
|
+
/** For element edits, after the patch is applied to `node` inside `source`: what the patch added to
|
|
372
|
+
* this element, plus the code total across the page, so batches can't add up past the limit. */
|
|
373
|
+
export function checkElementPatch(source, node, before, specials) {
|
|
374
|
+
if (!specials)
|
|
375
|
+
return [];
|
|
376
|
+
const alone = (n) => scanCode({ sections: [{ ...n, children: undefined }] });
|
|
377
|
+
const now = alone(node);
|
|
378
|
+
const old = alone(before);
|
|
379
|
+
const errors = now.errors.filter((e) => !old.errors.includes(e));
|
|
380
|
+
const total = scanCode(source).code;
|
|
381
|
+
if (now.code > old.code && total > NODE_CODE_BUDGET.hard)
|
|
382
|
+
errors.push(codeVolumeError(total));
|
|
383
|
+
return errors;
|
|
384
|
+
}
|
|
385
|
+
/** Translations are per-element text overrides, so they can hold placeholders too. Keyed by element id. */
|
|
386
|
+
export function checkContentPlaceholders(content, previous) {
|
|
387
|
+
return Object.entries(content || {})
|
|
388
|
+
.filter(([id, v]) => typeof v?.text === "string" && isDataPlaceholder(v.text) && previous?.[id]?.text !== v.text)
|
|
389
|
+
.map(([id]) => `"${id}" translation holds placeholder JSON for a script to fill. Translate real text. See get_build_guide → NATIVE FIRST.`);
|
|
390
|
+
}
|
|
391
|
+
export function validatePage(source, previous) {
|
|
329
392
|
const errors = [];
|
|
330
393
|
const warnings = [];
|
|
331
394
|
if (!source || typeof source !== "object" || !Array.isArray(source.sections)) {
|
|
@@ -395,9 +458,9 @@ export function validatePage(source) {
|
|
|
395
458
|
};
|
|
396
459
|
for (const s of source.sections)
|
|
397
460
|
checkTree(s, []);
|
|
398
|
-
const
|
|
399
|
-
errors.push(...
|
|
400
|
-
warnings.push(...
|
|
461
|
+
const code = checkNativeContent(source, previous);
|
|
462
|
+
errors.push(...code.errors);
|
|
463
|
+
warnings.push(...code.warnings);
|
|
401
464
|
return {
|
|
402
465
|
valid: errors.length === 0,
|
|
403
466
|
...(errors.length ? { errors } : {}),
|
package/dist/changelog.json
CHANGED
|
@@ -1,4 +1,18 @@
|
|
|
1
1
|
[
|
|
2
|
+
{
|
|
3
|
+
"v": "1.38.0",
|
|
4
|
+
"d": "05/11/2026",
|
|
5
|
+
"type": "Changed",
|
|
6
|
+
"en": "The install command no longer asks any questions: it opens the prod browser connect page and configures every AI app it detects on the machine…",
|
|
7
|
+
"vi": "Lệnh install nay không còn hỏi gì: mở thẳng trang kết nối prod trên trình duyệt và ghi cấu hình vào mọi ứng dụng AI phát hiện được trên máy (Claude…"
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
"v": "1.37.0",
|
|
11
|
+
"d": "04/11/2026",
|
|
12
|
+
"type": "Added",
|
|
13
|
+
"en": "A new native-first guide is now injected into get_build_guide's build guide, get_http_function's and get_site_custom_code's custom-code guide, and…",
|
|
14
|
+
"vi": "Hướng dẫn \"native first\" mới nay được chèn vào build guide của get_build_guide, custom-code guide của get_http_function và get_site_custom_code,…"
|
|
15
|
+
},
|
|
2
16
|
{
|
|
3
17
|
"v": "1.36.2",
|
|
4
18
|
"d": "29/10/2026",
|
|
@@ -26,19 +40,5 @@
|
|
|
26
40
|
"type": "Added",
|
|
27
41
|
"en": "New get_site_subscription tool reads a site's plan (current/default site): plan_name, status (active | expired | pending_payment | none),…",
|
|
28
42
|
"vi": "Tool mới get_site_subscription đọc gói cước của site (mặc định site hiện tại): plan_name, status (active | expired | pending_payment | none),…"
|
|
29
|
-
},
|
|
30
|
-
{
|
|
31
|
-
"v": "1.34.1",
|
|
32
|
-
"d": "14/10/2026",
|
|
33
|
-
"type": "Fixed",
|
|
34
|
-
"en": "validate_page's \"not a container\" warning now only fires for true leaf elements (text, image, button, inputs, datasets, etc.); container-like…",
|
|
35
|
-
"vi": "Cảnh báo \"not a container\" của validate_page nay chỉ xuất hiện với các element leaf thật sự (text, image, button, các input, dataset...); các…"
|
|
36
|
-
},
|
|
37
|
-
{
|
|
38
|
-
"v": "1.34.0",
|
|
39
|
-
"d": "14/10/2026",
|
|
40
|
-
"type": "Added",
|
|
41
|
-
"en": "New list_section_templates tool browses the designer-made section template library (categories, search by term, thumbnails) for starting a section…",
|
|
42
|
-
"vi": "Tool mới list_section_templates để duyệt thư viện mẫu section do designer tạo (theo danh mục, tìm kiếm bằng term, có thumbnail) làm điểm khởi đầu…"
|
|
43
43
|
}
|
|
44
44
|
]
|
package/dist/guides.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { NATIVE_FIRST_GUIDE } from "./builder/native-first.js";
|
|
1
2
|
export const HTTP_FUNCTION_GUIDE = `
|
|
2
3
|
# HTTP Function Guide
|
|
3
4
|
|
|
@@ -114,7 +115,7 @@ A "collection" is a custom DB table. To stand one up and use it from a function:
|
|
|
114
115
|
await T.deleteMany({ email: "a@b.com" }); // delete
|
|
115
116
|
const rows = await T.find({ … }).select([…]).limit(50); // query
|
|
116
117
|
(There is NO direct dashboard record-INSERT API — record writes MUST go through a function.
|
|
117
|
-
Deploy the function with the
|
|
118
|
+
Deploy the function with the edit_http_function MCP tool (action "add" or "replace_function"; update_http_function replaces the WHOLE file), then call it with run_function.)
|
|
118
119
|
|
|
119
120
|
## Built-in @webcake/* modules (first arg is always request; they auth via global.token — these run
|
|
120
121
|
## INSIDE the function sandbox, so they reach the /cms_function endpoints the dashboard JWT can't)
|
|
@@ -238,6 +239,8 @@ export const post_MyMembers = async (request) => {
|
|
|
238
239
|
export const CUSTOM_CODE_GUIDE = `
|
|
239
240
|
# Custom Code Guide
|
|
240
241
|
|
|
242
|
+
${NATIVE_FIRST_GUIDE}
|
|
243
|
+
|
|
241
244
|
Custom code is stored in site settings (applies to entire site, not per page).
|
|
242
245
|
|
|
243
246
|
## Injection points
|
package/dist/index.js
CHANGED
|
@@ -8,7 +8,7 @@ Usage: npx -y webcake-storefront-mcp [command] [options]
|
|
|
8
8
|
|
|
9
9
|
Commands:
|
|
10
10
|
(none) start the stdio MCP server (use this in IDE configs)
|
|
11
|
-
install
|
|
11
|
+
install connect to prod via the browser and configure your IDE(s) (--dev: step-by-step wizard with env choice)
|
|
12
12
|
uninstall remove the server from your IDE configs
|
|
13
13
|
login grab your token via the browser (saved to the local config db)
|
|
14
14
|
serve [--port N] run the remote Streamable-HTTP server (default 8787; or PORT env)
|