webcake-storefront-mcp 1.38.0 → 1.40.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/dist/api.js +233 -145
- package/dist/auth/login.js +22 -1
- package/dist/auth/oauth-server.js +19 -2
- package/dist/builder/attributes.js +1 -1
- package/dist/builder/guide.js +11 -5
- package/dist/builder/native-first.js +4 -5
- package/dist/builder/page.js +247 -13
- package/dist/builder/shape.js +174 -0
- package/dist/changelog.json +14 -14
- package/dist/config.js +13 -3
- package/dist/http.js +38 -17
- package/dist/index.js +2 -0
- package/dist/persistence/screenshot-client.js +208 -0
- package/dist/tools/builder-extras.js +172 -4
- package/dist/tools/builder.js +30 -23
- package/dist/tools/global-section-write.js +1 -1
- package/dist/tools/global-sources.js +25 -75
- package/dist/tools/page-draft.js +3 -2
- package/dist/tools/pages.js +32 -70
- package/dist/web-guide-scene.js +10 -4
- package/package.json +1 -1
package/dist/http.js
CHANGED
|
@@ -13,7 +13,7 @@ import { createServer } from "./server.js";
|
|
|
13
13
|
import { makeApi, resolveEnv, ENVIRONMENTS, DEFAULT_ENV } from "./config.js";
|
|
14
14
|
import { landingHtml, faviconSvg, ogImageSvg, normalizeLang, ICON_PNG } from "./web-guide.js";
|
|
15
15
|
import { privacyHtml, termsHtml } from "./legal.js";
|
|
16
|
-
import { registerClient, startAuthorize, completeAuthorize, exchangeToken, resolveAccessToken, revokeToken, authServerMetadata, protectedResourceMetadata, } from "./auth/oauth-server.js";
|
|
16
|
+
import { registerClient, startAuthorize, completeAuthorize, exchangeToken, resolveAccessToken, revokeToken, isDeadJwt, markJwtDead, authServerMetadata, protectedResourceMetadata, } from "./auth/oauth-server.js";
|
|
17
17
|
const MCP_PATH = "/mcp";
|
|
18
18
|
// OAuth 2.1 endpoints.
|
|
19
19
|
const WELL_KNOWN_PR = "/.well-known/oauth-protected-resource";
|
|
@@ -42,6 +42,10 @@ function header(req, name) {
|
|
|
42
42
|
const v = req.headers[name];
|
|
43
43
|
return Array.isArray(v) ? v[0] : v;
|
|
44
44
|
}
|
|
45
|
+
function setHeader(req, name, value) {
|
|
46
|
+
req.headers[name] = value;
|
|
47
|
+
req.rawHeaders.push(name, value);
|
|
48
|
+
}
|
|
45
49
|
/** Copy recognised query params onto request headers so downstream reads are uniform. */
|
|
46
50
|
function applyQueryAuth(req) {
|
|
47
51
|
const q = (req.url ?? "").indexOf("?");
|
|
@@ -288,6 +292,7 @@ async function handleOAuth(req, res, path) {
|
|
|
288
292
|
}
|
|
289
293
|
export async function startHttpServer(port) {
|
|
290
294
|
const transports = new Map();
|
|
295
|
+
const apis = new Map();
|
|
291
296
|
const httpServer = createHttpServer(async (req, res) => {
|
|
292
297
|
const path = (req.url ?? "").split("?")[0];
|
|
293
298
|
// ---- Favicon / brand icon ----
|
|
@@ -346,30 +351,38 @@ export async function startHttpServer(port) {
|
|
|
346
351
|
// ---- /mcp handling ----
|
|
347
352
|
// Accept credentials via query params for clients that can't set headers.
|
|
348
353
|
applyQueryAuth(req);
|
|
349
|
-
// Resolve an OAuth Bearer access token to { jwt, wsid }
|
|
350
|
-
//
|
|
354
|
+
// Resolve an OAuth Bearer access token to { jwt, wsid }. It WINS over a ?token= /
|
|
355
|
+
// x-webcake-jwt pair: a Bearer from our OAuth flow is what the last Connect issued, so
|
|
356
|
+
// it's the renewed credential when the URL still carries an old, expired one.
|
|
351
357
|
const bearer = bearerFrom(req);
|
|
352
358
|
const oauthCred = await resolveAccessToken(bearer);
|
|
353
359
|
if (oauthCred) {
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
req
|
|
357
|
-
}
|
|
358
|
-
if (oauthCred.wsid && req.headers["x-webcake-session-id"] == null) {
|
|
359
|
-
req.headers["x-webcake-session-id"] = oauthCred.wsid;
|
|
360
|
-
req.rawHeaders.push("x-webcake-session-id", oauthCred.wsid);
|
|
361
|
-
}
|
|
360
|
+
setHeader(req, "x-webcake-jwt", oauthCred.jwt);
|
|
361
|
+
if (oauthCred.wsid)
|
|
362
|
+
setHeader(req, "x-webcake-session-id", oauthCred.wsid);
|
|
362
363
|
}
|
|
363
|
-
|
|
364
|
-
|
|
364
|
+
const sidHeader = header(req, "mcp-session-id");
|
|
365
|
+
const jwt = header(req, "x-webcake-jwt");
|
|
366
|
+
// An open session picks up a renewed credential in place (no re-initialize needed).
|
|
367
|
+
const sessionApi = sidHeader ? apis.get(sidHeader) : undefined;
|
|
368
|
+
if (sessionApi && jwt && jwt !== sessionApi.token && !isDeadJwt(jwt)) {
|
|
369
|
+
sessionApi.switchToken(jwt);
|
|
370
|
+
const wsid = header(req, "x-webcake-session-id");
|
|
371
|
+
if (wsid)
|
|
372
|
+
sessionApi.switchSession(wsid);
|
|
373
|
+
}
|
|
374
|
+
// Enforce OAuth when enabled: no credential, or an expired/rejected WebCake token, gets
|
|
375
|
+
// 401 + WWW-Authenticate so the client (re)opens the Connect page by itself.
|
|
376
|
+
const dead = isDeadJwt(sessionApi ? sessionApi.token : jwt);
|
|
377
|
+
if (OAUTH_ENFORCED && (jwt == null || dead)) {
|
|
365
378
|
res.writeHead(401, {
|
|
366
|
-
"www-authenticate": `Bearer resource_metadata="${publicBase(req)}${WELL_KNOWN_PR}"`,
|
|
379
|
+
"www-authenticate": `Bearer error="invalid_token", resource_metadata="${publicBase(req)}${WELL_KNOWN_PR}"`,
|
|
367
380
|
"content-type": "application/json",
|
|
368
381
|
});
|
|
369
|
-
|
|
382
|
+
const why = dead ? "WebCake session expired — reconnect (Connect) to renew it." : "Authentication required — connect via OAuth.";
|
|
383
|
+
res.end(JSON.stringify({ error: "invalid_token", error_description: why }));
|
|
370
384
|
return;
|
|
371
385
|
}
|
|
372
|
-
const sidHeader = header(req, "mcp-session-id");
|
|
373
386
|
try {
|
|
374
387
|
// Reuse an existing session.
|
|
375
388
|
if (sidHeader && transports.has(sidHeader)) {
|
|
@@ -386,13 +399,21 @@ export async function startHttpServer(port) {
|
|
|
386
399
|
sessionIdGenerator: () => randomUUID(),
|
|
387
400
|
onsessioninitialized: (id) => {
|
|
388
401
|
transports.set(id, transport);
|
|
402
|
+
apis.set(id, api);
|
|
389
403
|
},
|
|
390
404
|
});
|
|
391
405
|
transport.onclose = () => {
|
|
392
|
-
if (transport.sessionId)
|
|
406
|
+
if (transport.sessionId) {
|
|
393
407
|
transports.delete(transport.sessionId);
|
|
408
|
+
apis.delete(transport.sessionId);
|
|
409
|
+
}
|
|
394
410
|
};
|
|
395
411
|
const api = apiFromRequest(req);
|
|
412
|
+
// Backend rejected the token → remember it, so the next request 401s into Connect.
|
|
413
|
+
api.onAuthExpired = async () => {
|
|
414
|
+
markJwtDead(api.token);
|
|
415
|
+
return null;
|
|
416
|
+
};
|
|
396
417
|
const server = createServer(api, { allowLocalFiles: false, tools: header(req, "x-webcake-tools") }); // remote: never read server-side files
|
|
397
418
|
await server.connect(transport);
|
|
398
419
|
await transport.handleRequest(req, res, body);
|
package/dist/index.js
CHANGED
|
@@ -58,6 +58,8 @@ async function main() {
|
|
|
58
58
|
// no env is required to start — auth (token + session) is set via env or `login`,
|
|
59
59
|
// and the site is chosen at runtime with switch_site.
|
|
60
60
|
const api = makeApi();
|
|
61
|
+
const { renewInBrowser } = await import("./auth/login.js");
|
|
62
|
+
api.onAuthExpired = renewInBrowser; // expired token → reopen Connect, then retry the call
|
|
61
63
|
const server = createServer(api, { allowLocalFiles: true }); // stdio = user's own machine
|
|
62
64
|
const transport = new StdioServerTransport();
|
|
63
65
|
await server.connect(transport);
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Thin screenshot client for the clone-fidelity loop: render a public URL (a
|
|
3
|
+
* page's /preview/<id>, or a reference page being cloned) to a PNG the model can
|
|
4
|
+
* SEE and compare against the reference.
|
|
5
|
+
*
|
|
6
|
+
* CAPABILITY LADDER (decided by the caller, NOT this file):
|
|
7
|
+
* 1. If the AGENT can screenshot itself (a shell + headless browser, e.g. Claude
|
|
8
|
+
* Code local), it should do that — fresh every time, no quota. The MCP
|
|
9
|
+
* `render_preview` tool is the FALLBACK for agents WITHOUT that ability
|
|
10
|
+
* (e.g. the claude.ai remote connector).
|
|
11
|
+
* 2. This client's default engine is Microlink ZERO-CONFIG (no key) — but its
|
|
12
|
+
* free tier is rate-limited PER IP (~50/day). That's fine for a local stdio
|
|
13
|
+
* user (their own IP) but a SHARED quota behind the serve-host proxy, so for
|
|
14
|
+
* remote/multi-user the host should point RENDER_SCREENSHOT_BASE at a KEYED
|
|
15
|
+
* engine (a proxy route that holds a ScreenshotOne/ApiFlash/Microlink-Pro key).
|
|
16
|
+
* 3. On quota/429 or any failure the caller SKIPS gracefully (never throws).
|
|
17
|
+
*
|
|
18
|
+
* Mirrors the Pexels client's direct-vs-proxy shape (see pexels-client.ts). The
|
|
19
|
+
* secret (if any) is resolved like the JWT — env or per-request header, never
|
|
20
|
+
* hard-coded (the repo is public). Requires global fetch (Node 18+).
|
|
21
|
+
*/
|
|
22
|
+
/** Microlink's free screenshot endpoint. `embed=screenshot.url` returns the PNG bytes directly. */
|
|
23
|
+
const MICROLINK_ENDPOINT = "https://api.microlink.io/";
|
|
24
|
+
/** Path of the keyed proxy's screenshot route (served by a host that holds a paid key). */
|
|
25
|
+
export const SCREENSHOT_PROXY_PATH = "/api/render/screenshot";
|
|
26
|
+
/** Fetch timeout — screenshots can be slow (full-page + webfont settle). */
|
|
27
|
+
const SCREENSHOT_TIMEOUT_MS = (() => {
|
|
28
|
+
const v = parseInt(process.env.WEBCAKE_HTTP_TIMEOUT_MS ?? "", 10);
|
|
29
|
+
return Number.isFinite(v) && v > 0 ? v : 60_000;
|
|
30
|
+
})();
|
|
31
|
+
/** Resolve the keyed-proxy base (host route that holds a paid screenshot key), if configured. */
|
|
32
|
+
export function resolveScreenshotProxyBase(override) {
|
|
33
|
+
const base = override ?? process.env.RENDER_SCREENSHOT_BASE;
|
|
34
|
+
return base && base.trim() !== "" ? base.replace(/\/+$/, "") : undefined;
|
|
35
|
+
}
|
|
36
|
+
/** Pull the per-request proxy base header (remote mode), if present. */
|
|
37
|
+
export function screenshotProxyBaseFromHeaders(headers) {
|
|
38
|
+
const v = headers?.["x-render-screenshot-base"];
|
|
39
|
+
const raw = Array.isArray(v) ? v[0] : v;
|
|
40
|
+
return raw && raw.trim() !== "" ? raw.trim() : undefined;
|
|
41
|
+
}
|
|
42
|
+
/** Which engine to try FIRST: "microlink" (free, default) or "proxy" (the keyed/self-hosted route). */
|
|
43
|
+
export function resolveScreenshotPrimary(override) {
|
|
44
|
+
const v = (override ?? process.env.RENDER_SCREENSHOT_PRIMARY ?? "").toLowerCase();
|
|
45
|
+
return v === "proxy" ? "proxy" : "microlink";
|
|
46
|
+
}
|
|
47
|
+
/** Optional Microlink Pro key (raises the free per-IP quota) — env or x-microlink-key header. */
|
|
48
|
+
export function resolveMicrolinkKey(override) {
|
|
49
|
+
const key = override ?? process.env.MICROLINK_API_KEY;
|
|
50
|
+
return key && key.trim() !== "" ? key.trim() : undefined;
|
|
51
|
+
}
|
|
52
|
+
export function microlinkKeyFromHeaders(headers) {
|
|
53
|
+
const v = headers?.["x-microlink-key"];
|
|
54
|
+
const raw = Array.isArray(v) ? v[0] : v;
|
|
55
|
+
return raw && raw.trim() !== "" ? raw.trim() : undefined;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Build the Microlink request URL. We force a cache bypass (`force=true` AND a
|
|
59
|
+
* nonce on the target URL) because the preview URL is stable across patch rounds
|
|
60
|
+
* — without it Microlink serves a STALE shot of the pre-patch page. Pure so the
|
|
61
|
+
* smoke test can assert the query shape without a network call.
|
|
62
|
+
*/
|
|
63
|
+
export function buildMicrolinkUrl(targetUrl, opts = {}, nonce = 0) {
|
|
64
|
+
// Nonce-bust the TARGET url itself (defends against any URL-keyed cache even if
|
|
65
|
+
// `force` is restricted on the free tier).
|
|
66
|
+
const bustTarget = targetUrl + (targetUrl.includes("?") ? "&" : "?") + "_=" + nonce;
|
|
67
|
+
const q = new URLSearchParams();
|
|
68
|
+
q.set("url", bustTarget);
|
|
69
|
+
q.set("screenshot", "true");
|
|
70
|
+
q.set("fullPage", String(opts.fullPage !== false));
|
|
71
|
+
q.set("meta", "false");
|
|
72
|
+
q.set("force", "true");
|
|
73
|
+
q.set("embed", "screenshot.url"); // respond with the PNG bytes, not JSON
|
|
74
|
+
if (opts.width && Number.isFinite(opts.width))
|
|
75
|
+
q.set("viewport.width", String(Math.round(opts.width)));
|
|
76
|
+
return `${MICROLINK_ENDPOINT}?${q.toString()}`;
|
|
77
|
+
}
|
|
78
|
+
/** Read a fetch Response into a ScreenshotResult, classifying quota/errors. */
|
|
79
|
+
async function readImageResponse(res, via) {
|
|
80
|
+
const ct = (res.headers.get("content-type") ?? "").toLowerCase();
|
|
81
|
+
if (res.ok && ct.startsWith("image/")) {
|
|
82
|
+
const buf = Buffer.from(await res.arrayBuffer());
|
|
83
|
+
return { ok: true, status: res.status, dataBase64: buf.toString("base64"), mimeType: ct.split(";")[0].trim(), bytes: buf.length, via };
|
|
84
|
+
}
|
|
85
|
+
// Non-image → an error (JSON or text). 429 == rate limit / quota.
|
|
86
|
+
const body = (await res.text()).slice(0, 300);
|
|
87
|
+
const quota = res.status === 429;
|
|
88
|
+
return {
|
|
89
|
+
ok: false,
|
|
90
|
+
status: res.status,
|
|
91
|
+
via,
|
|
92
|
+
quota_exhausted: quota,
|
|
93
|
+
error: quota
|
|
94
|
+
? `screenshot quota/rate-limit hit (HTTP 429) via ${via} — skip the visual check this round or configure a keyed engine`
|
|
95
|
+
: `${via} returned HTTP ${res.status}${body ? `: ${body}` : ""}`,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
/** Capture via Microlink directly (zero-config; per-IP free quota). */
|
|
99
|
+
export async function captureViaMicrolink(targetUrl, opts, key, nonce = 0) {
|
|
100
|
+
const url = buildMicrolinkUrl(targetUrl, opts, nonce);
|
|
101
|
+
try {
|
|
102
|
+
const res = await fetch(url, {
|
|
103
|
+
method: "GET",
|
|
104
|
+
headers: key ? { "x-api-key": key } : undefined,
|
|
105
|
+
signal: AbortSignal.timeout(SCREENSHOT_TIMEOUT_MS),
|
|
106
|
+
});
|
|
107
|
+
return await readImageResponse(res, "microlink");
|
|
108
|
+
}
|
|
109
|
+
catch (e) {
|
|
110
|
+
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
|
|
111
|
+
return { ok: false, status: 0, via: "microlink", error: `screenshot timed out after ${SCREENSHOT_TIMEOUT_MS}ms` };
|
|
112
|
+
}
|
|
113
|
+
return { ok: false, status: 0, via: "microlink", error: `network error calling Microlink: ${e?.message ?? e}` };
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
/** Capture via a keyed proxy route the host operates: GET <base>/api/render/screenshot?url=…&full_page=…&width=… */
|
|
117
|
+
export async function captureViaProxy(base, targetUrl, opts, nonce = 0) {
|
|
118
|
+
const q = new URLSearchParams();
|
|
119
|
+
q.set("url", targetUrl + (targetUrl.includes("?") ? "&" : "?") + "_=" + nonce);
|
|
120
|
+
q.set("full_page", String(opts.fullPage !== false));
|
|
121
|
+
if (opts.width && Number.isFinite(opts.width))
|
|
122
|
+
q.set("width", String(Math.round(opts.width)));
|
|
123
|
+
const url = `${base}${SCREENSHOT_PROXY_PATH}?${q.toString()}`;
|
|
124
|
+
try {
|
|
125
|
+
const res = await fetch(url, { method: "GET", signal: AbortSignal.timeout(SCREENSHOT_TIMEOUT_MS) });
|
|
126
|
+
return await readImageResponse(res, "proxy");
|
|
127
|
+
}
|
|
128
|
+
catch (e) {
|
|
129
|
+
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
|
|
130
|
+
return { ok: false, status: 0, via: "proxy", error: `screenshot timed out after ${SCREENSHOT_TIMEOUT_MS}ms calling proxy ${base}` };
|
|
131
|
+
}
|
|
132
|
+
return { ok: false, status: 0, via: "proxy", error: `network error calling screenshot proxy ${base}: ${e?.message ?? e}` };
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Capture a tall page as horizontal BANDS via the self-hosted Playwright route
|
|
137
|
+
* (`?tiles=1`) so the model reads each slice at a readable size. Microlink can't
|
|
138
|
+
* tile, so this REQUIRES a proxy host (RENDER_SCREENSHOT_BASE); without one it
|
|
139
|
+
* returns not_supported and the caller should fall back to a single full-page shot.
|
|
140
|
+
* Never throws.
|
|
141
|
+
*/
|
|
142
|
+
export async function captureScreenshotTiles(targetUrl, opts = {}, resolved = {}, nonce = 0) {
|
|
143
|
+
if (!resolved.proxyBase) {
|
|
144
|
+
return { ok: false, status: 0, not_supported: true, error: "tiling needs a Playwright host (RENDER_SCREENSHOT_BASE); Microlink can't tile" };
|
|
145
|
+
}
|
|
146
|
+
const q = new URLSearchParams();
|
|
147
|
+
q.set("url", targetUrl + (targetUrl.includes("?") ? "&" : "?") + "_=" + nonce);
|
|
148
|
+
q.set("tiles", "1");
|
|
149
|
+
q.set("full_page", "true");
|
|
150
|
+
if (opts.width && Number.isFinite(opts.width))
|
|
151
|
+
q.set("width", String(Math.round(opts.width)));
|
|
152
|
+
if (opts.bandHeight && Number.isFinite(opts.bandHeight))
|
|
153
|
+
q.set("band_height", String(Math.round(opts.bandHeight)));
|
|
154
|
+
const url = `${resolved.proxyBase}${SCREENSHOT_PROXY_PATH}?${q.toString()}`;
|
|
155
|
+
try {
|
|
156
|
+
const res = await fetch(url, { method: "GET", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(SCREENSHOT_TIMEOUT_MS) });
|
|
157
|
+
const ct = (res.headers.get("content-type") ?? "").toLowerCase();
|
|
158
|
+
if (res.ok && ct.includes("application/json")) {
|
|
159
|
+
const j = await res.json();
|
|
160
|
+
return {
|
|
161
|
+
ok: true,
|
|
162
|
+
status: res.status,
|
|
163
|
+
mimeType: j.mimeType,
|
|
164
|
+
pageHeight: j.page_height,
|
|
165
|
+
width: j.width,
|
|
166
|
+
truncated: j.truncated === true,
|
|
167
|
+
tiles: (j.tiles ?? []).map((t) => ({ y: t.y, height: t.height, dataBase64: t.data })),
|
|
168
|
+
via: "proxy",
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
const body = (await res.text()).slice(0, 300);
|
|
172
|
+
return { ok: false, status: res.status, quota_exhausted: res.status === 429, error: `tiles proxy returned HTTP ${res.status}${body ? `: ${body}` : ""}` };
|
|
173
|
+
}
|
|
174
|
+
catch (e) {
|
|
175
|
+
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
|
|
176
|
+
return { ok: false, status: 0, error: `tiles request timed out after ${SCREENSHOT_TIMEOUT_MS}ms` };
|
|
177
|
+
}
|
|
178
|
+
return { ok: false, status: 0, error: `network error calling tiles proxy ${resolved.proxyBase}: ${e?.message ?? e}` };
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Capture a screenshot with AUTOMATIC FALLOVER between the two engines:
|
|
183
|
+
* - Microlink direct (free, zero-config) and
|
|
184
|
+
* - the proxy route (a keyed API or the VPS's self-hosted Playwright engine).
|
|
185
|
+
* Tries `primary` first; if it fails — especially Microlink hitting its per-IP
|
|
186
|
+
* quota (HTTP 429) — it retries the other engine. So a free quota is used up
|
|
187
|
+
* first, then traffic auto-switches to the unlimited self-hosted route. With no
|
|
188
|
+
* proxyBase configured it's Microlink only. Never throws; on total failure
|
|
189
|
+
* returns the most informative error (quota_exhausted set when that was the cause).
|
|
190
|
+
*/
|
|
191
|
+
export async function captureScreenshot(targetUrl, opts = {}, resolved = {}, nonce = 0) {
|
|
192
|
+
const primary = resolved.primary ?? resolveScreenshotPrimary();
|
|
193
|
+
const micro = () => captureViaMicrolink(targetUrl, opts, resolved.microlinkKey, nonce);
|
|
194
|
+
const proxy = () => (resolved.proxyBase ? captureViaProxy(resolved.proxyBase, targetUrl, opts, nonce) : null);
|
|
195
|
+
// No fallback engine available → single attempt.
|
|
196
|
+
if (!resolved.proxyBase)
|
|
197
|
+
return micro();
|
|
198
|
+
const first = primary === "proxy" ? proxy() : micro();
|
|
199
|
+
const r1 = await first;
|
|
200
|
+
if (r1.ok)
|
|
201
|
+
return r1;
|
|
202
|
+
// Primary failed (quota or error) → fall over to the other engine.
|
|
203
|
+
const r2 = await (primary === "proxy" ? micro() : proxy());
|
|
204
|
+
if (r2.ok)
|
|
205
|
+
return r2;
|
|
206
|
+
// Both failed → prefer the non-quota error (more actionable); else the quota one.
|
|
207
|
+
return r1.quota_exhausted && !r2.quota_exhausted ? r2 : r1;
|
|
208
|
+
}
|
|
@@ -1,11 +1,114 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import { resolvePreviewUrl } from "../config.js";
|
|
2
|
+
import { resolvePreviewUrl, draftPreviewUrl } from "../config.js";
|
|
3
|
+
import { captureScreenshot, resolveMicrolinkKey, resolveScreenshotProxyBase } from "../persistence/screenshot-client.js";
|
|
4
|
+
import { validatePage, missingBreakpoints } from "../builder/page.js";
|
|
5
|
+
import { checkShape } from "../builder/shape.js";
|
|
6
|
+
import { BREAKPOINT_KEYS } from "../builder/grid.js";
|
|
7
|
+
import { CODE_BUDGET, codeUsage } from "../builder/native-first.js";
|
|
3
8
|
import { getCachedUpload, setCachedUpload } from "../persistence/imageCache.js";
|
|
4
9
|
import { parse as parseHtml } from "node-html-parser";
|
|
5
10
|
import { stat, readFile } from "node:fs/promises";
|
|
6
11
|
import { homedir } from "node:os";
|
|
7
12
|
import { join } from "node:path";
|
|
8
13
|
import { fileURLToPath } from "node:url";
|
|
14
|
+
/** Checks the SAVED site before publish_site sends it: anything here that is an error either makes
|
|
15
|
+
* /publish fail (500) or ships a broken storefront, so it blocks the publish. */
|
|
16
|
+
export async function preflightSite(api) {
|
|
17
|
+
const errors = [];
|
|
18
|
+
const warnings = [];
|
|
19
|
+
const settings = await api.getSiteSettings();
|
|
20
|
+
// Saved data is judged by what BREAKS the live storefront: checkShape's renderer crashes
|
|
21
|
+
// (verified against builderx_api qwik) block; editor-only breakage warns. Everything else validatePage refuses on a NEW
|
|
22
|
+
// write (missing/duplicate id, native-first volume…) already publishes today, so it only warns.
|
|
23
|
+
const judge = (name, src, v) => {
|
|
24
|
+
const shape = checkShape(src);
|
|
25
|
+
const crash = shape.errors.filter((e) => !shape.editorOnly.includes(e)); // the live site blanks
|
|
26
|
+
const fatal = (v.errors || []).filter((e) => crash.includes(e));
|
|
27
|
+
const rest = (v.errors || []).filter((e) => !crash.includes(e));
|
|
28
|
+
errors.push(...fatal.slice(0, 10).map((e) => `${name}: ${e}`));
|
|
29
|
+
if (fatal.length > 10)
|
|
30
|
+
errors.push(`${name}: …and ${fatal.length - 10} more (run validate_page on this page).`);
|
|
31
|
+
warnings.push(...rest.slice(0, 5).map((e) => `${name}: ${e}`));
|
|
32
|
+
};
|
|
33
|
+
const bps = settings.breakpoints;
|
|
34
|
+
const bpKeys = bps && typeof bps === "object" && !Array.isArray(bps)
|
|
35
|
+
? Object.keys(bps).filter((k) => Array.isArray(bps[k]) && bps[k].length === 2)
|
|
36
|
+
: [];
|
|
37
|
+
if (!bpKeys.length)
|
|
38
|
+
warnings.push("Site settings have no usable breakpoints; publish fills in the standard four (bp1..bp4).");
|
|
39
|
+
const usage = codeUsage(settings);
|
|
40
|
+
for (const kind of ["script", "css"])
|
|
41
|
+
if (usage[kind].used > CODE_BUDGET[kind].hard)
|
|
42
|
+
errors.push(`Site ${kind} is ${usage[kind].used} chars (ceiling ${CODE_BUDGET[kind].hard}). Shrink it with update_site_custom_code, moving per-element rules into native element styles, then publish.`);
|
|
43
|
+
const res = await api.listPages();
|
|
44
|
+
const list = (res && res.data) || res || [];
|
|
45
|
+
let checked = 0;
|
|
46
|
+
for (const p of Array.isArray(list) ? list : []) {
|
|
47
|
+
const raw = p && p.source && p.source.source;
|
|
48
|
+
if (raw == null || raw === "")
|
|
49
|
+
continue;
|
|
50
|
+
const name = p.is_homepage ? "/ (home)" : `/${p.slug || p.id}`;
|
|
51
|
+
let src;
|
|
52
|
+
try {
|
|
53
|
+
src = typeof raw === "string" ? JSON.parse(raw) : raw;
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
errors.push(`${name}: saved source is not valid JSON.`);
|
|
57
|
+
continue;
|
|
58
|
+
}
|
|
59
|
+
if (!src || !Array.isArray(src.sections)) {
|
|
60
|
+
warnings.push(`${name}: saved source has no sections array; skipped.`);
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
checked++;
|
|
64
|
+
const v = validatePage(src);
|
|
65
|
+
judge(name, src, v);
|
|
66
|
+
const keys = bpKeys.length ? bpKeys : BREAKPOINT_KEYS;
|
|
67
|
+
const m = missingBreakpoints(src, keys);
|
|
68
|
+
if (m.missing)
|
|
69
|
+
warnings.push(`${name}: ${m.missing}/${m.total} elements lack a breakpoint (${keys.join(", ")}) and render unstyled at that width, e.g. ${m.sample.join(", ")}.`);
|
|
70
|
+
if (v.warnings && v.warnings.length)
|
|
71
|
+
warnings.push(`${name}: ${v.warnings.length} validate_page warning(s), e.g. ${v.warnings[0]}`);
|
|
72
|
+
}
|
|
73
|
+
// Popups and the cart drawer publish with the site too (global_sources); a crash-level shape in
|
|
74
|
+
// one blanks it on every page. Same rules, same "native-first only warns" policy.
|
|
75
|
+
const globals = await api.globalSourcesForSave().catch(() => []);
|
|
76
|
+
for (const g of Array.isArray(globals) ? globals : []) {
|
|
77
|
+
const name = `${g.component} ${g.id}`;
|
|
78
|
+
const root = g.source;
|
|
79
|
+
const src = root && Array.isArray(root.sections) ? root : { sections: Array.isArray(root) ? root : root ? [root] : [] };
|
|
80
|
+
judge(name, src, validatePage(src));
|
|
81
|
+
}
|
|
82
|
+
return { ok: !errors.length, pages_checked: checked, errors, warnings };
|
|
83
|
+
}
|
|
84
|
+
/** Fetch the live page after a publish. Its HTML carries the site breakpoints as `bps = [...]`;
|
|
85
|
+
* an empty list makes the storefront's detectBp throw, so the page renders blank. Retries while
|
|
86
|
+
* the CDN catches up. */
|
|
87
|
+
export async function checkLive(url, tries = 3, waitMs = 5000) {
|
|
88
|
+
let problems = [];
|
|
89
|
+
let unverified;
|
|
90
|
+
for (let i = 0; i < tries; i++) {
|
|
91
|
+
if (i)
|
|
92
|
+
await new Promise((r) => setTimeout(r, waitMs));
|
|
93
|
+
problems = [];
|
|
94
|
+
unverified = undefined;
|
|
95
|
+
try {
|
|
96
|
+
const r = await fetch(`${url}${url.includes("?") ? "&" : "?"}_mcp=${Date.now()}`, { signal: AbortSignal.timeout(15000) });
|
|
97
|
+
const html = await r.text();
|
|
98
|
+
// A WAF block or fresh-domain DNS lag says nothing about the publish: unverified, not failed.
|
|
99
|
+
if (!r.ok)
|
|
100
|
+
unverified = `HTTP ${r.status}`;
|
|
101
|
+
else if (/\bbps\s*=\s*\[\s*\]/.test(html))
|
|
102
|
+
problems.push("Published HTML has an empty breakpoint list (bps = []): the storefront cannot pick a layout and renders blank.");
|
|
103
|
+
}
|
|
104
|
+
catch (e) {
|
|
105
|
+
unverified = `Could not fetch the live page: ${e?.message || e}`;
|
|
106
|
+
}
|
|
107
|
+
if (!problems.length && !unverified)
|
|
108
|
+
break;
|
|
109
|
+
}
|
|
110
|
+
return { url, ok: !problems.length, problems, ...(unverified ? { unverified } : {}) };
|
|
111
|
+
}
|
|
9
112
|
const ALLOWED_IMG = /^image\/(jpe?g|png|webp)$/;
|
|
10
113
|
const LOCAL_MAX = 200 * 1024 * 1024; // 200 MB, matches the backend multipart limit
|
|
11
114
|
/** Is this entry a LOCAL filesystem path (vs an http(s) URL or data: URI)? */
|
|
@@ -215,30 +318,95 @@ Processes up to 20 entries per call in parallel; non jpeg/png/webp inputs are co
|
|
|
215
318
|
// ── Publish the site ────────────────────────────────────────────────────────
|
|
216
319
|
server.tool("publish_site", `Publish the whole site live — snapshots all current page sources into the live (published) version.
|
|
217
320
|
Note: BuilderX publishes at the SITE level, not per page; publishing makes every saved page go live.
|
|
218
|
-
Two-step safety: dry_run=true (default) describes what will happen; dry_run=false
|
|
321
|
+
Two-step safety: dry_run=true (default) runs the preflight and describes what will happen; dry_run=false publishes.
|
|
322
|
+
Preflight: every saved page through validate_page, site CSS/JS against the ceiling, breakpoints. Any error BLOCKS the
|
|
323
|
+
publish (fix it first); warnings are listed. After publishing, the live homepage is fetched and checked; success is
|
|
324
|
+
false when it is still broken (e.g. bps = []).`, {
|
|
219
325
|
dry_run: z.boolean().default(true).describe("Preview (true) or publish for real (false)"),
|
|
220
326
|
}, ({ dry_run }) => handle(async () => {
|
|
221
327
|
const preview_url = await resolvePreviewUrl(api);
|
|
328
|
+
const preflight = await preflightSite(api);
|
|
222
329
|
if (dry_run) {
|
|
223
330
|
return {
|
|
224
331
|
dry_run: true,
|
|
225
332
|
preview_url,
|
|
226
|
-
|
|
333
|
+
preflight,
|
|
334
|
+
note: preflight.ok
|
|
335
|
+
? "This will publish ALL saved pages of the site live. Call again with dry_run=false to publish."
|
|
336
|
+
: "Publishing is BLOCKED until the preflight errors are fixed.",
|
|
227
337
|
};
|
|
228
338
|
}
|
|
339
|
+
if (!preflight.ok)
|
|
340
|
+
return { error: "BLOCKED: preflight failed, nothing published.", ...preflight };
|
|
229
341
|
// builderx_spa's Publish button sends `domain: this.link` (the site's live URL) in the
|
|
230
342
|
// /publish body — without it the backend publishes to an expiring preview. preview_url
|
|
231
343
|
// is exactly that link (resolvePreviewUrl == link(): primary_domain wins, else subdomain).
|
|
232
344
|
const res = await api.publishSite(preview_url ? { domain: preview_url } : {});
|
|
233
345
|
const data = (res && res.data) || res;
|
|
346
|
+
const live_check = preview_url ? await checkLive(preview_url) : null;
|
|
234
347
|
return {
|
|
235
|
-
success:
|
|
348
|
+
success: !live_check || live_check.ok,
|
|
349
|
+
...(live_check && !live_check.ok
|
|
350
|
+
? { error: "The publish API answered OK but the live site is still broken. Do not report success; show the user live_check.problems." }
|
|
351
|
+
: {}),
|
|
352
|
+
live_check,
|
|
353
|
+
warnings: preflight.warnings,
|
|
236
354
|
published_at: data && data.published_at,
|
|
237
355
|
site: data && data.name,
|
|
238
356
|
preview_url,
|
|
239
357
|
screenshots: "Homepage screenshots (desktop 1920_1080 + mobile 430_932) are captured in the background after a publish (at most once an hour). About a minute later get_site_info returns them in preview_img — open one with invoke_tool('read_image', { url }) to check the live result visually.",
|
|
240
358
|
};
|
|
241
359
|
}));
|
|
360
|
+
// ── See the saved draft, like the designer looking at the canvas ─────────────
|
|
361
|
+
server.tool("preview_page", `LOOK at a saved page before publishing: screenshots of the SAVED (unpublished) draft at desktop and
|
|
362
|
+
mobile width, through the editor's own Preview host (it renders page.source + the CSS /save built for it).
|
|
363
|
+
A designer judges the canvas by eye; do the same after every build or batch of edits: compare with the
|
|
364
|
+
brief (section order, hierarchy, colors, spacing, alignment, overflowing or cut text, images, mobile
|
|
365
|
+
stacking), fix with update_page_element(s), then preview again until it matches. Nothing goes live.
|
|
366
|
+
Engine: Microlink free tier (~50 shots/day per IP) unless RENDER_SCREENSHOT_BASE / MICROLINK_API_KEY is
|
|
367
|
+
set; when it can't capture, open the returned url with your own browser if you have one. The
|
|
368
|
+
screenshot service fetches the draft url (a third party sees the unpublished page; self-host via
|
|
369
|
+
RENDER_SCREENSHOT_BASE to avoid that).`, {
|
|
370
|
+
page_id: z.string().describe("Page to preview"),
|
|
371
|
+
widths: z.array(z.number().int().min(320).max(2560)).max(3).default([1280, 420])
|
|
372
|
+
.describe("Viewport widths; default desktop 1280 + mobile 420 (the site's bp1 and bp4)"),
|
|
373
|
+
full_page: z.boolean().default(true).describe("Whole scrollable page (default) or just the first screen"),
|
|
374
|
+
}, async ({ page_id, widths, full_page }) => {
|
|
375
|
+
try {
|
|
376
|
+
const res = await api.listPages();
|
|
377
|
+
const page = ((res && res.data) || res || []).find((p) => p && p.id === page_id);
|
|
378
|
+
if (!page)
|
|
379
|
+
return { content: [{ type: "text", text: JSON.stringify({ error: `Page ${page_id} not found` }) }], isError: true };
|
|
380
|
+
// /save stamps published_at: the draft preview opens for ~10 min (PreviewExpire), content untouched.
|
|
381
|
+
await api.refreshDraftPreview();
|
|
382
|
+
const url = draftPreviewUrl(api, page.is_homepage ? "" : page.slug || "");
|
|
383
|
+
const engine = { proxyBase: resolveScreenshotProxyBase(), microlinkKey: resolveMicrolinkKey() };
|
|
384
|
+
const content = [];
|
|
385
|
+
const failed = [];
|
|
386
|
+
for (const width of widths) {
|
|
387
|
+
const r = await captureScreenshot(url, { fullPage: full_page, width }, engine, Date.now());
|
|
388
|
+
if (r.ok && r.dataBase64) {
|
|
389
|
+
content.push({ type: "text", text: `${width}px wide:` });
|
|
390
|
+
content.push({ type: "image", data: r.dataBase64, mimeType: r.mimeType || "image/png" });
|
|
391
|
+
}
|
|
392
|
+
else
|
|
393
|
+
failed.push(`${width}px: ${r.quota_exhausted ? "screenshot quota reached" : r.error || `HTTP ${r.status}`}`);
|
|
394
|
+
}
|
|
395
|
+
content.unshift({
|
|
396
|
+
type: "text",
|
|
397
|
+
text: JSON.stringify({
|
|
398
|
+
url,
|
|
399
|
+
page: page.name || page.slug,
|
|
400
|
+
...(failed.length ? { failed, hint: "Open the url in your own browser if you can; otherwise check the source with validate_page and retry later." } : {}),
|
|
401
|
+
next: "Compare with the brief. Fix what differs with update_page_element(s), then preview_page again.",
|
|
402
|
+
}),
|
|
403
|
+
});
|
|
404
|
+
return { content };
|
|
405
|
+
}
|
|
406
|
+
catch (e) {
|
|
407
|
+
return { content: [{ type: "text", text: JSON.stringify({ error: e?.message || String(e) }) }], isError: true };
|
|
408
|
+
}
|
|
409
|
+
});
|
|
242
410
|
// ── Ingest reference HTML / URL into a blueprint ────────────────────────────
|
|
243
411
|
function blueprintFromHtml(html) {
|
|
244
412
|
const root = parseHtml(html, { blockTextElements: { script: false, style: false } });
|
package/dist/tools/builder.js
CHANGED
|
@@ -126,30 +126,37 @@ export function buildPageSeo(seo = {}) {
|
|
|
126
126
|
* REPLACED (omitted → stored as "null", wiping page_mask/seo). So: one call per branch, and the
|
|
127
127
|
* last call always resends the page's current settings with the changes merged in. */
|
|
128
128
|
export async function applyPageMeta(api, pageId, { name, slug, is_homepage, settings, seo }) {
|
|
129
|
-
if (name != null)
|
|
130
|
-
await api.updatePage(pageId, { name });
|
|
131
129
|
if (is_homepage)
|
|
132
130
|
await api.updatePage(pageId, { is_homepage: true });
|
|
133
131
|
const seoBlock = seo ? buildPageSeo(seo) : {};
|
|
134
|
-
if (
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
132
|
+
if (slug || settings || Object.keys(seoBlock).length || name != null) {
|
|
133
|
+
// ponytail: no get-page-by-id route, so this pulls the full page list (with sources) once.
|
|
134
|
+
const res = await api.listPages();
|
|
135
|
+
const list = res?.data || res?.pages || res;
|
|
136
|
+
let cur = (Array.isArray(list) ? list : []).find((p) => p.id === pageId)?.settings;
|
|
137
|
+
if (typeof cur === "string")
|
|
138
|
+
try {
|
|
139
|
+
cur = JSON.parse(cur);
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
cur = null;
|
|
143
|
+
}
|
|
144
|
+
if (!cur || typeof cur !== "object")
|
|
145
|
+
cur = {};
|
|
146
|
+
const next = { ...cur, ...(settings || {}) };
|
|
147
|
+
if (Object.keys(seoBlock).length)
|
|
148
|
+
next.seo = { ...(next.seo || {}), ...seoBlock };
|
|
149
|
+
// Renaming (update_name_page) decodes page.settings and splits seo.title on "|": it 500s on a
|
|
150
|
+
// page with no settings or no seo.title, i.e. every page create_page makes. Give it the
|
|
151
|
+
// editor's default title first (builderx_spa utils/editor_v2/seo.js DEFAULT_TITLE).
|
|
152
|
+
const needsTitle = name != null && typeof next.seo?.title !== "string";
|
|
153
|
+
if (needsTitle)
|
|
154
|
+
next.seo = { ...(next.seo || {}), title: "{{name_page}} | {{name_site}}" };
|
|
155
|
+
if (slug || settings || Object.keys(seoBlock).length || needsTitle)
|
|
156
|
+
await api.updatePage(pageId, { ...(slug ? { slug } : {}), settings: next });
|
|
157
|
+
}
|
|
158
|
+
if (name != null)
|
|
159
|
+
await api.updatePage(pageId, { name });
|
|
153
160
|
}
|
|
154
161
|
/** Normalize a page slug to what the storefront matches on. The storefront routes by the
|
|
155
162
|
* RAW path segment (e.g. "/cart" → path ["cart"]) and looks up `page.slug == "cart"`, so a
|
|
@@ -275,7 +282,7 @@ ONE page per site for type main (homepage) / error / maintain, and slugs are uni
|
|
|
275
282
|
}
|
|
276
283
|
}
|
|
277
284
|
// Expand runtime -> bp1..bp4 so the saved source actually renders on the storefront.
|
|
278
|
-
finalizeForRender(parsed, await api.getSiteBreakpoints());
|
|
285
|
+
finalizeForRender(parsed, await api.getSiteBreakpoints(), await api.getSiteDefaultGrid());
|
|
279
286
|
// createPage saves the page AND its source in one call (source is required there).
|
|
280
287
|
const created = await api.createPage({ name, source: parsed, ...(typeNum != null ? { type: typeNum } : {}) });
|
|
281
288
|
const pageId = newPageId(created);
|
|
@@ -381,7 +388,7 @@ Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
|
|
|
381
388
|
return { error: "Validation failed — not saving.", validation };
|
|
382
389
|
// Expand the newly-added section's runtime -> bp1..bp4 (existing sections are
|
|
383
390
|
// already in breakpoint shape and are left untouched).
|
|
384
|
-
finalizeForRender(source, await api.getSiteBreakpoints());
|
|
391
|
+
finalizeForRender(source, await api.getSiteBreakpoints(), await api.getSiteDefaultGrid());
|
|
385
392
|
const saved = await api.updatePageSource(page_id, { source });
|
|
386
393
|
return {
|
|
387
394
|
success: true,
|
|
@@ -77,7 +77,7 @@ Two-step safety: dry_run=true (default) previews which pages change; dry_run=fal
|
|
|
77
77
|
const validation = validatePage(wrap);
|
|
78
78
|
if (!validation.valid)
|
|
79
79
|
return { error: "Section failed validation.", validation };
|
|
80
|
-
finalizeForRender(wrap, await api.getSiteBreakpoints());
|
|
80
|
+
finalizeForRender(wrap, await api.getSiteBreakpoints(), await api.getSiteDefaultGrid());
|
|
81
81
|
const finalNode = wrap.sections[0];
|
|
82
82
|
// Resolve target pages + inject the node into each one's source.
|
|
83
83
|
const allPages = await loadPages(api);
|