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/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 } and inject both headers
350
- // so apiFromRequest picks them up — existing header/query paths remain untouched.
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
- if (req.headers["x-webcake-jwt"] == null) {
355
- req.headers["x-webcake-jwt"] = oauthCred.jwt;
356
- req.rawHeaders.push("x-webcake-jwt", oauthCred.jwt);
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
- // Enforce OAuth when enabled: a request with no recognised credential gets 401.
364
- if (OAUTH_ENFORCED && !oauthCred && req.headers["x-webcake-jwt"] == null) {
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
- res.end(JSON.stringify({ error: "invalid_token", error_description: "Authentication required — connect via OAuth." }));
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 actually publishes.`, {
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
- note: "This will publish ALL saved pages of the site live. Call again with dry_run=false to publish.",
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: true,
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 } });
@@ -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 (!slug && !settings && !Object.keys(seoBlock).length)
135
- return;
136
- // ponytail: no get-page-by-id route, so this pulls the full page list (with sources) once.
137
- const res = await api.listPages();
138
- const list = res?.data || res?.pages || res;
139
- let cur = (Array.isArray(list) ? list : []).find((p) => p.id === pageId)?.settings;
140
- if (typeof cur === "string")
141
- try {
142
- cur = JSON.parse(cur);
143
- }
144
- catch {
145
- cur = null;
146
- }
147
- if (!cur || typeof cur !== "object")
148
- cur = {};
149
- const next = { ...cur, ...(settings || {}) };
150
- if (Object.keys(seoBlock).length)
151
- next.seo = { ...(next.seo || {}), ...seoBlock };
152
- await api.updatePage(pageId, { ...(slug ? { slug } : {}), settings: next });
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);