Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
fix(cli): preflight MCP edits and preserve screenshot diagnostics (#6505)
Oleg Isonen7ae2a8141e06
diff --git a/packages/cli/src/commands/mcp-preview.test.ts b/packages/cli/src/commands/mcp-preview.test.tsindex bf7c5d1228..74e2612a16 100644--- a/packages/cli/src/commands/mcp-preview.test.ts+++ b/packages/cli/src/commands/mcp-preview.test.ts@@ -746,6 +746,33 @@ test("times out a stalled screenshot after preview start and releases its sessioexpect(stop).toHaveBeenCalledOnce();});+test("preserves browser phase timeout details instead of the outer watchdog", async () => {+ const phaseError = Object.assign(+ new Error("Page did not reach load within 5ms."),+ { code: "SCREENSHOT_TIMEOUT" }+ );+ const captureScreenshot = vi.fn(async () => {+ await new Promise((resolve) => setTimeout(resolve, 10));+ throw phaseError;+ });+ const handlers = createMcpPreviewHandlers({+ preview: {+ status: vi.fn(() => ({ running: false as const })),+ startAndWait: vi.fn(),+ resolveUrl: vi.fn(),+ },+ captureScreenshot,+ });++ await expect(+ handlers.captureScreenshot({+ url: "https://example.com",+ viewport: { width: 1280, height: 720 },+ timeout: 5,+ })+ ).rejects.toBe(phaseError);+});+test("leaves time to start a fallback browser within the MCP timeout", async () => {const createBrowserScreenshotSession = vi.fn(async (options) => {if (options.browserPath === "/usr/bin/chromium") {diff --git a/packages/cli/src/commands/mcp-preview.ts b/packages/cli/src/commands/mcp-preview.tsindex f447f69e9f..a38a89a203 100644--- a/packages/cli/src/commands/mcp-preview.ts+++ b/packages/cli/src/commands/mcp-preview.ts@@ -218,6 +218,7 @@ const createScreenshotTimeoutError = (timeout: number) =>new Error(`Screenshot capture did not finish within ${timeout}ms.`),{ code: "SCREENSHOT_TIMEOUT" });+const screenshotTimeoutGraceMs = 1_000;const getPreviewSource = (source: PreviewSource | undefined): PreviewSource =>source ?? defaultPreviewSource;@@ -318,8 +319,10 @@ export const createMcpPreviewHandlers = ({resetSession?: () => Promise<void>) => {try {- return await withTimeout(operation(), timeout, () =>- createScreenshotTimeoutError(timeout)+ return await withTimeout(+ operation(),+ timeout + screenshotTimeoutGraceMs,+ () => createScreenshotTimeoutError(timeout));} catch (error) {if (resetSession !== undefined) {diff --git a/packages/cli/src/commands/mcp.test.ts b/packages/cli/src/commands/mcp.test.tsindex d017141683..85428cb60d 100644--- a/packages/cli/src/commands/mcp.test.ts+++ b/packages/cli/src/commands/mcp.test.ts@@ -37,6 +37,7 @@ const {createMcpRunErrorPayload,createMcpSingleOpCallErrorPayload,createMcpStatusReporter,+ assertMcpToolServerSupport,getCliUpdateInstructions,getLoadedProjectSessionSnapshot,getMcpOperationInput,@@ -69,6 +70,26 @@ test("instructs connected agents to update an outdated MCP CLI", () => {expect(getCliUpdateInstructions(undefined)).toBeUndefined();});+test("checks API contract compatibility before committing MCP edits", () => {+ const contract = {+ clientVersion: "public-api:client",+ serverVersion: "public-api:server",+ supportedOperationIds: new Set<string>(),+ missingServerOperationIds: [],+ negotiated: true,+ } as const;++ expect(() => assertMcpToolServerSupport("update-page", contract)).toThrow(+ /Restart the MCP server with the latest CLI/+ );+ expect(() =>+ assertMcpToolServerSupport("update-page", contract, true)+ ).not.toThrow();+ expect(() =>+ assertMcpToolServerSupport("list-pages", contract)+ ).not.toThrow();+});+test("disposes an MCP host when its operation fails", async () => {const dispose = vi.fn(async () => undefined);diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.tsindex 96ab6cc885..512e878e95 100644--- a/packages/cli/src/commands/mcp.ts+++ b/packages/cli/src/commands/mcp.ts@@ -64,6 +64,7 @@ import {import { HandledCliError, isHandledCliError } from "../errors";import { loadJSONFile } from "../fs-utils";import {+ assertCliEditingContractVersion,assertCliServerOperationSupported,createCliProjectRestorePointStorage,createCliProjectSession,@@ -72,6 +73,7 @@ import {getCliProjectRestorePointsFile,getCliServerApiContract,getSupportedPublicApiOperations,+ requiresCliEditingContract,type CliServerApiContract,writeCliProjectSessionPreviewDataFile,type CliProjectSession,@@ -2034,6 +2036,7 @@ const createCliMcpHost = async ({createProjectSession: () => session,onProjectSessionChange: previewFreshness.markStale,executeOperation: async ({ command, input, dryRun }) => {+ assertMcpToolServerSupport(command, apiContract, dryRun === true);const operationInput = getMcpOperationInput(command, input);const textAssetFeedback = await prepareTextAssetWriteFeedback({command,@@ -2046,6 +2049,7 @@ const createCliMcpHost = async ({input: operationInput,connection: apiConnection,createProjectSession: () => session,+ apiContract,dryRun,});if (dryRun !== true && shouldInvalidatePreview(command)) {@@ -2314,13 +2318,17 @@ type CliMcpCore = ReturnType<const assertMcpToolServerSupport = (tool: string,- contract: CliServerApiContract+ contract: CliServerApiContract,+ dryRun = false) => {const operation = publicApiOperationByCommand.get(tool as PublicApiCommand);- if (- operation !== undefined &&- publicApiOperationRequiresServerSupport(operation)- ) {+ if (operation === undefined) {+ return;+ }+ if (requiresCliEditingContract(operation, dryRun)) {+ assertCliEditingContractVersion(contract);+ }+ if (publicApiOperationRequiresServerSupport(operation)) {assertCliServerOperationSupported(operation.id, contract);}};@@ -2409,7 +2417,7 @@ export const mcpSingleOpCall = async (options: McpSingleOpCallOptions) => {recordToolFailure,recordToolSuccess,}) => {- assertMcpToolServerSupport(tool, apiContract);+ assertMcpToolServerSupport(tool, apiContract, options.dryRun === true);const core = createCliMcpCore(host);const persistedCheckpoint =tool === "checkpoint.ack"@@ -2566,7 +2574,11 @@ const runMcpProjectsBatch = async ({core.listTools().map((tool) => [tool.name, tool]));for (const call of project.calls.slice(startCall)) {- assertMcpToolServerSupport(call.tool, apiContract);+ assertMcpToolServerSupport(+ call.tool,+ apiContract,+ call.dryRun === true+ );const tool = tools.get(call.tool);assertMcpBatchMutationApproved({projectId: project.id,@@ -2704,7 +2716,7 @@ export const mcpRun = async (options: McpRunOptions) => {disposeHost = mcpHost.dispose;scope = mcpHost.scope;for (const call of calls) {- assertMcpToolServerSupport(call.tool, apiContract);+ assertMcpToolServerSupport(call.tool, apiContract, call.dryRun === true);}core = createCliMcpCore(host);} catch (error) {@@ -2956,6 +2968,7 @@ export const __testing__ = {getCliUpdateInstructions,createMcpStatusReporter,formatMcpStatusLine,+ assertMcpToolServerSupport,assertSingleOpCallToolSupported,createMcpSingleOpCallErrorPayload,createMcpResourceErrorPayload: (error: unknown, elapsedMs: number) => ({diff --git a/packages/cli/src/preview-server/readiness.test.ts b/packages/cli/src/preview-server/readiness.test.tsindex aaefa1896c..384bc26f86 100644--- a/packages/cli/src/preview-server/readiness.test.ts+++ b/packages/cli/src/preview-server/readiness.test.ts@@ -138,9 +138,15 @@ test("requires the exact generated project even when build assets match", async},createDependencies({ fetch }))- ).rejects.toThrow(- "Preview server at http://127.0.0.1:5173/ did not serve the expected generated project."- );+ ).rejects.toMatchObject({+ code: "PREVIEW_PROJECT_MISMATCH",+ issues: [+ {+ code: "preview_project_mismatch",+ constraint: "latest_generated_project_served",+ },+ ],+ });});test("accepts the generated preview with the expected project marker", async () => {@@ -233,7 +239,50 @@ test("rejects stale preview servers that serve a previous build", async () => {},createDependencies({ fetch }))- ).rejects.toThrow(- "Preview server at http://127.0.0.1:5173/ did not serve the latest build assets."+ ).rejects.toMatchObject({+ code: "PREVIEW_ASSETS_STALE",+ message: expect.stringContaining(+ "The preview server did not serve the latest generated build assets. Stop the existing preview server on this port, then retry."+ ),+ issues: [+ {+ code: "preview_assets_stale",+ path: [],+ constraint: "latest_generated_assets_served",+ },+ ],+ });+});++test("reports when a regenerated session version is not served", async () => {+ const fetch = vi.fn(+ async () =>+ new Response(+ '<html data-ws-project="project" data-ws-version="4"></html>'+ ));++ await expect(+ waitForPreviewReady(+ "http://127.0.0.1:5173/",+ {+ timeoutMs: 1,+ intervalMs: 5,+ requiredProject: { projectId: "project", version: 5 },+ },+ createDependencies({ fetch })+ )+ ).rejects.toMatchObject({+ code: "PREVIEW_PROJECT_MISMATCH",+ message: expect.stringContaining(+ "The preview server did not serve the generated project version just prepared."+ ),+ issues: [+ {+ code: "preview_project_mismatch",+ path: [],+ constraint: "latest_generated_project_served",+ },+ ],+ });});diff --git a/packages/cli/src/preview-server/readiness.ts b/packages/cli/src/preview-server/readiness.tsindex bbee525537..2317f04982 100644--- a/packages/cli/src/preview-server/readiness.ts+++ b/packages/cli/src/preview-server/readiness.ts@@ -69,7 +69,12 @@ type PreviewProbeFailure = {const createPreviewReadinessError = (url: string,- code: "PREVIEW_HTTP_ERROR" | "PREVIEW_READINESS_FAILED",+ code:+ | "PREVIEW_HTTP_ERROR"+ | "PREVIEW_READINESS_FAILED"+ | "PREVIEW_ASSETS_STALE"+ | "PREVIEW_PROJECT_MISMATCH"+ | "PREVIEW_READINESS_TIMEOUT",issue: PreviewProbeFailure) =>Object.assign(new Error(`${issue.message} Preview URL: ${url}`), {@@ -214,14 +219,20 @@ export const waitForPreviewReady = async (await dependencies.sleep(intervalMs);}if (sawUnexpectedProject) {- throw new Error(- `Preview server at ${url} did not serve the expected generated project. Stop the existing preview server on this port, then retry.`- );+ throw createPreviewReadinessError(url, "PREVIEW_PROJECT_MISMATCH", {+ code: "preview_project_mismatch",+ message:+ "The preview server did not serve the generated project version just prepared. Stop the existing preview server on this port, then retry.",+ constraint: "latest_generated_project_served",+ });}if (sawStaleServer) {- throw new Error(- `Preview server at ${url} did not serve the latest build assets. Stop the existing preview server on this port, then retry.`- );+ throw createPreviewReadinessError(url, "PREVIEW_ASSETS_STALE", {+ code: "preview_assets_stale",+ message:+ "The preview server did not serve the latest generated build assets. Stop the existing preview server on this port, then retry.",+ constraint: "latest_generated_assets_served",+ });}if (lastProbeFailure !== undefined) {throw createPreviewReadinessError(@@ -232,7 +243,11 @@ export const waitForPreviewReady = async (lastProbeFailure);}- throw new Error(`Preview server did not become ready at ${url}.`);+ throw createPreviewReadinessError(url, "PREVIEW_READINESS_TIMEOUT", {+ code: "preview_readiness_timeout",+ message: `The preview server did not become ready within ${timeoutMs}ms.`,+ constraint: "preview_server_ready",+ });};export const getPreviewCssAssetNames = async (diff --git a/packages/cli/src/project-session-api.test.ts b/packages/cli/src/project-session-api.test.tsindex 5c993833c0..9e99f87cf0 100644--- a/packages/cli/src/project-session-api.test.ts+++ b/packages/cli/src/project-session-api.test.ts@@ -218,7 +218,7 @@ describe("project session api adapter", () => {expect(session.executeServerOperation).not.toHaveBeenCalled();});- test("does not require a local mutation in the server operation list", async () => {+ test("checks the editing contract without requiring an operation id", async () => {const session = {initialize: vi.fn(async () => undefined),mutate: vi.fn(async () => ({ diagnostics: [] })),@@ -231,7 +231,7 @@ describe("project session api adapter", () => {) as unknown as CreateProjectSession;const getServerApiContract = vi.fn(async () => ({clientVersion: "public-api:client",- serverVersion: "public-api:server",+ serverVersion: "public-api:client",supportedOperationIds: new Set<string>(),missingServerOperationIds: [],negotiated: true,@@ -249,11 +249,45 @@ describe("project session api adapter", () => {getServerApiContract,});- expect(getServerApiContract).not.toHaveBeenCalled();+ expect(getServerApiContract).toHaveBeenCalledOnce();expect(session.initialize).toHaveBeenCalledOnce();expect(session.mutate).toHaveBeenCalledOnce();});+ test("rejects an incompatible editing contract before initializing a session", async () => {+ const session = {+ initialize: vi.fn(async () => undefined),+ mutate: vi.fn(),+ read: vi.fn(),+ refresh: vi.fn(),+ executeServerOperation: vi.fn(),+ };++ await expect(+ executeProjectSessionApiOperation({+ command: "create-page",+ input: { name: "Pricing", path: "/pricing" },+ connection: {+ projectId: "project-1",+ origin: "https://example.com",+ authToken: "token",+ },+ createProjectSession: vi.fn(+ () => session+ ) as unknown as CreateProjectSession,+ getServerApiContract: async () => ({+ clientVersion: "public-api:client",+ serverVersion: "public-api:server",+ supportedOperationIds: new Set<string>(),+ missingServerOperationIds: [],+ negotiated: true,+ }),+ })+ ).rejects.toMatchObject({ code: "API_CONTRACT_MISMATCH" });+ expect(session.initialize).not.toHaveBeenCalled();+ expect(session.mutate).not.toHaveBeenCalled();+ });+test("refreshes local namespaces before local-capable commands when requested", async () => {const session = {initialize: vi.fn(async () => undefined),diff --git a/packages/cli/src/project-session-api.ts b/packages/cli/src/project-session-api.tsindex 4196a6cbb4..be54a71acf 100644--- a/packages/cli/src/project-session-api.ts+++ b/packages/cli/src/project-session-api.ts@@ -11,9 +11,12 @@ import {type ProjectSessionDiagnostic,} from "@webstudio-is/project-build/project-session";import {+ assertCliEditingContractVersion,assertCliServerOperationSupported,createCliProjectSession,getCliServerApiContract,+ requiresCliEditingContract,+ type CliServerApiContract,} from "./project-session";import type { ApiConnection } from "./api-connection";@@ -75,6 +78,7 @@ export const executeProjectSessionApiOperation = async ({connection,createProjectSession = createCliProjectSession,getServerApiContract = getCliServerApiContract,+ apiContract,dryRun = false,refresh = false,}: {@@ -83,6 +87,7 @@ export const executeProjectSessionApiOperation = async ({connection: ApiConnection;createProjectSession?: CreateProjectSession;getServerApiContract?: typeof getCliServerApiContract;+ apiContract?: CliServerApiContract;dryRun?: boolean;refresh?: boolean;}) => {@@ -101,11 +106,18 @@ export const executeProjectSessionApiOperation = async ({const requiresServerSupport =runtimeOperationId === undefined ||publicApiOperationRequiresServerSupport(operation);- const contract = requiresServerSupport- ? await getServerApiContract(connection)- : undefined;- if (requiresServerSupport && contract !== undefined) {- assertCliServerOperationSupported(operation.id, contract);+ const requiresEditingContract = requiresCliEditingContract(operation, dryRun);+ const contract =+ requiresServerSupport || requiresEditingContract+ ? (apiContract ?? (await getServerApiContract(connection)))+ : undefined;+ if (contract !== undefined) {+ if (requiresServerSupport) {+ assertCliServerOperationSupported(operation.id, contract);+ }+ if (requiresEditingContract) {+ assertCliEditingContractVersion(contract);+ }}const session = createProjectSession({ connection });await session.initialize();diff --git a/packages/cli/src/project-session.test.ts b/packages/cli/src/project-session.test.tsindex f8a2c82551..495a608567 100644--- a/packages/cli/src/project-session.test.ts+++ b/packages/cli/src/project-session.test.ts@@ -14,6 +14,7 @@ import {createIssueReportFailure,createIssueReportFailureTracker,addIssueReportRuntime,+ assertCliEditingContractVersion,getCliServerApiContract,getCliProjectSessionFile,getCliProjectRestorePointsFile,@@ -687,6 +688,38 @@ describe("CLI/server operation contract", () => {).toBe(false);expect(operations.some((operation) => operation.serverOnly)).toBe(false);});++ test("rejects edits early when the MCP CLI uses a different API contract", () => {+ expect(() =>+ assertCliEditingContractVersion({+ clientVersion: "public-api:client",+ serverVersion: "public-api:server",+ supportedOperationIds: new Set(),+ missingServerOperationIds: [],+ negotiated: true,+ })+ ).toThrow(+ "The Webstudio CLI and API use different editing contracts. Expected public-api:server, received public-api:client. Restart the MCP server with the latest CLI; if it is already current, retry after the Webstudio API deployment is updated."+ );++ expect(() =>+ assertCliEditingContractVersion({+ clientVersion: "public-api:client",+ serverVersion: "public-api:client",+ supportedOperationIds: new Set(),+ missingServerOperationIds: [],+ negotiated: true,+ })+ ).not.toThrow();+ expect(() =>+ assertCliEditingContractVersion({+ clientVersion: "public-api:client",+ supportedOperationIds: new Set(),+ missingServerOperationIds: [],+ negotiated: false,+ })+ ).not.toThrow();+ });});const previewMarketplaceProduct = {diff --git a/packages/cli/src/project-session.ts b/packages/cli/src/project-session.tsindex 88f1bb34f2..4b7c314d9d 100644--- a/packages/cli/src/project-session.ts+++ b/packages/cli/src/project-session.ts@@ -146,6 +146,35 @@ export const assertCliServerOperationSupported = ();};+export const requiresCliEditingContract = (+ operation: Pick<+ (typeof publicApiOperations)[number],+ "method" | "writeNamespaces"+ >,+ dryRun = false+) =>+ dryRun === false &&+ operation.method === "mutation" &&+ operation.writeNamespaces.length > 0;++export const assertCliEditingContractVersion = (+ contract: CliServerApiContract+) => {+ if (+ contract.negotiated === false ||+ contract.serverVersion === contract.clientVersion+ ) {+ return;+ }++ throw Object.assign(+ new Error(+ `The Webstudio CLI and API use different editing contracts. Expected ${contract.serverVersion}, received ${contract.clientVersion}. Restart the MCP server with the latest CLI; if it is already current, retry after the Webstudio API deployment is updated.`+ ),+ { code: "API_CONTRACT_MISMATCH" }+ );+};+type PublicBuildSnapshot = Omit<BuilderBuildDataSnapshot,"dataSources" | "pages"