Skip to content

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.

feat: Improve MCP validation errors with actionable guidance (#5881)

Oleg Isonen2808f06808fe
diff --git a/apps/builder/app/services/api-errors.server.ts b/apps/builder/app/services/api-errors.server.ts
index 9964b77459..8297660583 100644
--- a/apps/builder/app/services/api-errors.server.ts
+++ b/apps/builder/app/services/api-errors.server.ts
@@ -1,8 +1,18 @@
import { TRPCError } from "@trpc/server";
+type ApiErrorOptions = {
+ webstudioCode?: string;
+ issues?: unknown;
+};
+
export const throwApiError = (
code: "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT",
- message: string
+ message: string,
+ options: ApiErrorOptions = {}
): never => {
- throw new TRPCError({ code, message });
+ const cause =
+ options.webstudioCode === undefined && options.issues === undefined
+ ? undefined
+ : Object.assign(new Error(message), options);
+ throw new TRPCError({ code, message, cause });
};
diff --git a/apps/builder/app/services/api-runtime.server.test.ts b/apps/builder/app/services/api-runtime.server.test.ts
index 3cb9586aaa..a2f295603f 100644
--- a/apps/builder/app/services/api-runtime.server.test.ts
+++ b/apps/builder/app/services/api-runtime.server.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, test } from "vitest";
+import { TRPCError } from "@trpc/server";
import { createDefaultPages } from "@webstudio-is/project-build";
import type { CompactBuild } from "@webstudio-is/project-build";
import { createEmptyWebstudioFragment } from "@webstudio-is/project-build/runtime/component-template";
@@ -78,6 +79,27 @@ describe("api runtime adapter", () => {
).resolves.toMatchObject({ query: "Home" });
});
+ test("preserves actionable validation issues in public api errors", async () => {
+ await expect(
+ executeApiRuntimeOperation({
+ id: "pages.create",
+ build: createBuild(),
+ input: { projectId: "project-1", name: false, path: "/pricing" },
+ })
+ ).rejects.toMatchObject({
+ code: "BAD_REQUEST",
+ cause: expect.objectContaining({
+ webstudioCode: "INVALID_INPUT",
+ issues: [
+ expect.objectContaining({
+ path: ["name"],
+ constraint: "type:string",
+ }),
+ ],
+ }),
+ } satisfies Partial<TRPCError>);
+ });
+
test("awaits async runtime mutations before reading mutation payload", async () => {
const mutation = await executeApiRuntimeOperation({
id: "instances.insertComponent",
diff --git a/apps/builder/app/services/api-runtime.server.ts b/apps/builder/app/services/api-runtime.server.ts
index b5e0a476e6..712804d588 100644
--- a/apps/builder/app/services/api-runtime.server.ts
+++ b/apps/builder/app/services/api-runtime.server.ts
@@ -41,7 +41,14 @@ export const executeApiRuntimeOperation = async <Result>({
});
} catch (error) {
if (error instanceof BuilderRuntimeError) {
- return throwApiError(error.code, error.message);
+ return throwApiError(
+ error.code === "INVALID_INPUT" ? "BAD_REQUEST" : error.code,
+ error.message,
+ {
+ webstudioCode: error.code,
+ issues: error.issues,
+ }
+ );
}
throw error;
}
diff --git a/packages/cli/src/commands/api-command.test.ts b/packages/cli/src/commands/api-command.test.ts
index 3cbcb962e7..7fc055e0bc 100644
--- a/packages/cli/src/commands/api-command.test.ts
+++ b/packages/cli/src/commands/api-command.test.ts
@@ -653,6 +653,45 @@ test("maps api not found errors to not found json", async () => {
});
});
+test("prints actionable validation issues in CLI JSON", async () => {
+ mockConfig();
+ const issue = {
+ code: "invalid_expression",
+ path: ["values", "title"],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: 'pageTitle ?? "Pricing"',
+ detail: "Unexpected token at 1:4",
+ };
+ apiCalls.getPage.mockRejectedValue(
+ Object.assign(new Error("Page input is invalid."), {
+ code: "INVALID_INPUT",
+ issues: [issue],
+ })
+ );
+
+ await expect(
+ apiCommand(
+ { command: "get-page", page: "page-1", json: true },
+ dependencies
+ )
+ ).rejects.toThrow("Handled CLI error");
+
+ expect(getLastJsonOutput()).toEqual({
+ ok: false,
+ error: {
+ code: "INVALID_INPUT",
+ message: "Page input is invalid.",
+ issues: [issue],
+ },
+ meta: {
+ command: "get-page",
+ projectId: "project-1",
+ durationMs: expect.any(Number),
+ },
+ });
+});
+
test("explains missing Builder API access instead of leaking token ownership errors", async () => {
mockConfig();
createCliProjectSession.mockImplementationOnce(() => ({
diff --git a/packages/cli/src/commands/api-command.ts b/packages/cli/src/commands/api-command.ts
index 6bbe2a3292..f50d1af407 100644
--- a/packages/cli/src/commands/api-command.ts
+++ b/packages/cli/src/commands/api-command.ts
@@ -14,7 +14,9 @@ import {
getCliServerApiContract,
} from "../project-session";
import {
+ getCliErrorIssues,
getCliErrorMessage,
+ getCliErrorSummary,
getStableErrorCode,
isMissingApiAccessError,
} from "../error-codes";
@@ -3020,14 +3022,15 @@ export const apiCommand = async (
});
}
} catch (error) {
- const message = getCliErrorMessage(error, options.command);
+ const issues = getCliErrorIssues(error);
if (options.json === true) {
const code = getErrorCode(error);
printJson({
ok: false,
error: {
code,
- message,
+ message: getCliErrorSummary(error, options.command),
+ ...(issues === undefined ? {} : { issues }),
retry: getRetryHint(code),
},
meta: {
@@ -3037,7 +3040,7 @@ export const apiCommand = async (
},
});
} else {
- console.error(message);
+ console.error(getCliErrorMessage(error, options.command));
}
throw new HandledCliError();
}
diff --git a/packages/cli/src/commands/mcp.test.ts b/packages/cli/src/commands/mcp.test.ts
index d6530c78cf..d1bdce7b9e 100644
--- a/packages/cli/src/commands/mcp.test.ts
+++ b/packages/cli/src/commands/mcp.test.ts
@@ -348,8 +348,10 @@ test("preserves structured input issues in MCP shell errors", () => {
code: "INVALID_INPUT",
issues: [
{
+ code: "mutually_exclusive_fields",
path: ["pagePath"],
message: "pageId and pagePath are mutually exclusive.",
+ constraint: "use_page_id_or_page_path",
},
],
}),
@@ -361,8 +363,10 @@ test("preserves structured input issues in MCP shell errors", () => {
code: "INVALID_INPUT",
issues: [
{
+ code: "mutually_exclusive_fields",
path: ["pagePath"],
message: "pageId and pagePath are mutually exclusive.",
+ constraint: "use_page_id_or_page_path",
},
],
},
diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts
index 9bcca31199..03400c7cff 100644
--- a/packages/cli/src/commands/mcp.ts
+++ b/packages/cli/src/commands/mcp.ts
@@ -15,9 +15,12 @@ import {
import { importProjectBundleWithAssets } from "@webstudio-is/http-client";
import packageJson from "../../package.json" with { type: "json" };
import type { ProjectSessionSnapshot } from "@webstudio-is/project-build/project-session";
+import type { SemanticValidationIssue } from "@webstudio-is/project-build/runtime/errors";
import { resolveApiConnection } from "../api-connection";
import {
+ getCliErrorIssues,
getCliErrorMessage,
+ getCliErrorSummary,
getStableErrorCode,
isMissingApiAccessError,
} from "../error-codes";
@@ -895,6 +898,7 @@ const createMcpRunCheckpointStopPayload = ({
};
const getMcpRunError = (error: unknown) => {
+ const issues = getCliErrorIssues(error);
if (
isRecord(error) &&
typeof error.message === "string" &&
@@ -904,32 +908,37 @@ const getMcpRunError = (error: unknown) => {
code: isMissingApiAccessError(error)
? "UNAUTHORIZED"
: (error.code ?? "MCP_TOOL_FAILED"),
- message: getCliErrorMessage(error),
- ...(Array.isArray(error.issues) ? { issues: error.issues } : {}),
+ message: getCliErrorSummary(error),
+ ...(issues === undefined ? {} : { issues }),
};
}
const code = isMissingApiAccessError(error)
? "UNAUTHORIZED"
: (getStableErrorCode(error) ?? "MCP_TOOL_FAILED");
- const message = getCliErrorMessage(error);
- return { code, message };
+ const message = getCliErrorSummary(error);
+ return { code, message, ...(issues === undefined ? {} : { issues }) };
};
const validateSingleOpCallInput = (tool: string, input: unknown) => {
if (tool !== "audit" || isRecord(input) === false) {
return;
}
- const issues: Array<{ path: string[]; message: string }> = [];
+ const issues: SemanticValidationIssue[] = [];
if (input.pageId !== undefined && input.pagePath !== undefined) {
issues.push({
path: ["pagePath"],
+ code: "mutually_exclusive_fields",
message: "pageId and pagePath are mutually exclusive.",
+ constraint: "use_page_id_or_page_path",
+ example: "/pricing",
});
}
if (input.rendered === true && input.cursor !== undefined) {
issues.push({
path: ["cursor"],
+ code: "incompatible_fields",
message: "cursor cannot be combined with rendered audit.",
+ constraint: "omit_cursor_for_rendered_audit",
});
}
if (issues.length > 0) {
diff --git a/packages/cli/src/error-codes.test.ts b/packages/cli/src/error-codes.test.ts
index eab6304c39..c44222e6ad 100644
--- a/packages/cli/src/error-codes.test.ts
+++ b/packages/cli/src/error-codes.test.ts
@@ -4,6 +4,7 @@ import {
getStableErrorCode,
isMissingApiAccessError,
} from "./error-codes";
+import { BuilderRuntimeError } from "@webstudio-is/project-build/runtime/errors";
describe("getStableErrorCode", () => {
test("reads direct stable error codes", () => {
@@ -22,6 +23,28 @@ describe("getStableErrorCode", () => {
});
describe("getCliErrorMessage", () => {
+ test("formats actionable semantic issues for human output", () => {
+ const error = new BuilderRuntimeError(
+ "INVALID_INPUT",
+ "Operation input is invalid.",
+ {
+ issues: [
+ {
+ code: "invalid_type",
+ path: ["values", "title"],
+ message: "Expected a string",
+ constraint: "type:string",
+ example: "Pricing",
+ },
+ ],
+ }
+ );
+
+ expect(getCliErrorMessage(error)).toBe(
+ 'Operation input is invalid.\nvalues.title: Expected a string (type:string). Example: "Pricing".'
+ );
+ });
+
test("turns API procedure skew into actionable CLI update guidance", () => {
const error = {
data: {
diff --git a/packages/cli/src/error-codes.ts b/packages/cli/src/error-codes.ts
index 039552a6ee..a4fee757c6 100644
--- a/packages/cli/src/error-codes.ts
+++ b/packages/cli/src/error-codes.ts
@@ -2,6 +2,10 @@ import {
getApiCompatibilityMessage,
getApiErrorCode,
} from "@webstudio-is/http-client";
+import {
+ formatValidationIssues,
+ getValidationIssues,
+} from "@webstudio-is/project-build/runtime/errors";
const missingProjectOwnerForTokenPattern =
/^Project owner can't be found for token\b/;
@@ -34,7 +38,7 @@ export const isMissingApiAccessError = (error: unknown) => {
return missingProjectOwnerForTokenPattern.test(message);
};
-export const getCliErrorMessage = (error: unknown, command = "mcp") => {
+export const getCliErrorSummary = (error: unknown, command = "mcp") => {
const compatibilityMessage = getApiCompatibilityMessage(error, {
updateCommand: "npm install -g webstudio@latest",
runLatestCommand: `npx webstudio@latest ${command}`,
@@ -48,3 +52,13 @@ export const getCliErrorMessage = (error: unknown, command = "mcp") => {
}
return message;
};
+
+export const getCliErrorMessage = (error: unknown, command = "mcp") => {
+ const message = getCliErrorSummary(error, command);
+ const issues = getValidationIssues(error);
+ return issues === undefined || issues.length === 0
+ ? message
+ : `${message}\n${formatValidationIssues(issues)}`;
+};
+
+export const getCliErrorIssues = getValidationIssues;
diff --git a/packages/cli/src/project-session-api.test.ts b/packages/cli/src/project-session-api.test.ts
index 2aab261ed1..cfa3303443 100644
--- a/packages/cli/src/project-session-api.test.ts
+++ b/packages/cli/src/project-session-api.test.ts
@@ -295,8 +295,18 @@ describe("project session api adapter", () => {
diagnostics: [
{
level: "error",
- code: "PROJECT_SESSION_BUSY",
- message: "Project session snapshot changed on disk.",
+ code: "INVALID_INPUT",
+ message: "Page input is invalid.",
+ issues: [
+ {
+ code: "invalid_expression",
+ path: ["values", "title"],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: 'pageTitle ?? "Pricing"',
+ detail: "Unexpected token",
+ },
+ ],
},
],
})),
@@ -319,8 +329,14 @@ describe("project session api adapter", () => {
) as unknown as CreateProjectSession,
})
).rejects.toMatchObject({
- code: "PROJECT_SESSION_BUSY",
- message: "Project session snapshot changed on disk.",
+ code: "INVALID_INPUT",
+ message: "Page input is invalid.",
+ issues: [
+ expect.objectContaining({
+ path: ["values", "title"],
+ constraint: "valid_webstudio_expression",
+ }),
+ ],
});
});
});
diff --git a/packages/cli/src/project-session-api.ts b/packages/cli/src/project-session-api.ts
index 3c8facb106..7446589089 100644
--- a/packages/cli/src/project-session-api.ts
+++ b/packages/cli/src/project-session-api.ts
@@ -8,6 +8,7 @@ import type { BuilderNamespace } from "@webstudio-is/project-build/contracts/nam
import {
serializeProjectSessionMeta,
type ProjectSessionEnvelope,
+ type ProjectSessionDiagnostic,
} from "@webstudio-is/project-build/project-session";
import {
assertCliServerOperationSupported,
@@ -31,18 +32,23 @@ const uniqueNamespaces = (
): readonly BuilderNamespace[] => [...new Set(namespaces)];
const getSessionError = (envelope: {
- diagnostics: readonly { level: string; code?: string; message: string }[];
+ diagnostics: readonly ProjectSessionDiagnostic[];
}) => envelope.diagnostics.find((diagnostic) => diagnostic.level === "error");
-const createProjectSessionApiError = (diagnostic: {
- code?: string;
- message: string;
-}) => {
- const error = new Error(diagnostic.message) as Error & { code?: string };
+const createProjectSessionApiError = (
+ diagnostic: Pick<ProjectSessionDiagnostic, "code" | "message" | "issues">
+) => {
+ const error = new Error(diagnostic.message) as Error & {
+ code?: string;
+ issues?: ProjectSessionDiagnostic["issues"];
+ };
if (diagnostic.code !== undefined) {
error.name = diagnostic.code;
error.code = diagnostic.code;
}
+ if (diagnostic.issues !== undefined) {
+ error.issues = diagnostic.issues;
+ }
return error;
};
diff --git a/packages/http-client/src/index.test.ts b/packages/http-client/src/index.test.ts
index 8e78eb1354..7c2fca24da 100644
--- a/packages/http-client/src/index.test.ts
+++ b/packages/http-client/src/index.test.ts
@@ -250,6 +250,11 @@ test("extracts api error codes", () => {
data: { code: "NOT_FOUND", webstudioCode: "PROJECT_NOT_PUBLISHED" },
})
).toBe("PROJECT_NOT_PUBLISHED");
+ expect(
+ getApiErrorCode({
+ data: { code: "BAD_REQUEST", webstudioCode: "INVALID_INPUT" },
+ })
+ ).toBe("INVALID_INPUT");
expect(
getApiErrorCode({ data: { code: "SOME_PRIVATE_CODE" } })
).toBeUndefined();
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index dc4b4f68af..e448e93942 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -14,6 +14,7 @@ import { runtimeOperationContracts } from "./contracts/builder-runtime";
import { getInputSchemaMetadata } from "./contracts/input-schema";
import { pageExpressionFieldHint } from "./runtime/pages";
import { imageDescriptionsSetInput } from "./runtime/assets";
+import { BuilderRuntimeError } from "./runtime/errors";
import {
createProjectSessionMcpCore,
createProjectSessionMcpServer,
@@ -624,6 +625,9 @@ describe("project session mcp adapter", () => {
data: expect.objectContaining({ oneOf: expect.any(Array) }),
error: expect.objectContaining({
required: ["code", "message"],
+ properties: expect.objectContaining({
+ issues: expect.objectContaining({ type: "array" }),
+ }),
}),
}),
}),
@@ -6351,16 +6355,18 @@ describe("project session mcp adapter", () => {
structuredContent: {
ok: false,
error: {
- message: expect.stringContaining('"email":"[email protected]"'),
+ message: "Tool input is invalid.",
code: "INVALID_INPUT",
issues: expect.arrayContaining([
expect.objectContaining({
path: ["email"],
message: expect.any(String),
+ example: "[email protected]",
}),
expect.objectContaining({
path: ["description"],
message: expect.any(String),
+ example: "stringxxxx",
}),
]),
},
@@ -6368,13 +6374,49 @@ describe("project session mcp adapter", () => {
},
})
);
- expect(result.structuredContent).toEqual(
- expect.objectContaining({
- error: expect.objectContaining({
- message: expect.stringContaining('"description":"stringxxxx"'),
- }),
- })
- );
+ } finally {
+ await close();
+ }
+ });
+
+ test("returns equivalent structured runtime validation issues", async () => {
+ const issue = {
+ code: "invalid_expression",
+ path: ["values", "title"],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: 'pageTitle ?? "Pricing"',
+ detail: "Unexpected token at 1:4",
+ };
+ const server = await createProjectSessionMcpServer({
+ operations: publicMcpOperations,
+ createProjectSession: createSessionFactory(),
+ executeOperation: createExecuteOperation(async () => {
+ throw new BuilderRuntimeError(
+ "INVALID_INPUT",
+ "Page input is invalid.",
+ {
+ issues: [issue],
+ }
+ );
+ }),
+ });
+ const { client, close } = await createConnectedClient(server);
+
+ try {
+ const result = await client.callTool({
+ name: "list-pages",
+ arguments: {},
+ });
+ expect(result.structuredContent).toEqual({
+ ok: false,
+ error: {
+ code: "INVALID_INPUT",
+ message: "Page input is invalid.",
+ issues: [issue],
+ },
+ meta: {},
+ });
} finally {
await close();
}
diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.ts
index d83d607f66..11b53f7935 100644
--- a/packages/project-build/src/mcp.ts
+++ b/packages/project-build/src/mcp.ts
@@ -69,6 +69,12 @@ import {
} from "./runtime/component-catalog";
import { parseWebstudioJsxFragment } from "./runtime/jsx";
import { webstudioJsxFragmentInputDescription } from "./runtime/jsx/bindings";
+import {
+ getValidationIssues,
+ getZodValidationIssues,
+ semanticValidationIssuesJsonSchema,
+ type SemanticValidationIssue,
+} from "./runtime/errors";
import { z } from "zod";
type PublicMcpOperationMethod = "query" | "mutation";
@@ -2188,6 +2194,12 @@ const previewTools: readonly ProjectSessionMcpTool[] = [
}),
];
+type McpStructuredError = {
+ code: string;
+ message: string;
+ issues?: readonly SemanticValidationIssue[];
+};
+
type ProjectSessionMcpStructuredContent =
| {
ok: true;
@@ -2201,7 +2213,7 @@ type ProjectSessionMcpStructuredContent =
| {
ok: false;
data: unknown;
- error: { code: string; message: string };
+ error: McpStructuredError;
meta: {
session?:
| ReturnType<typeof serializeProjectSessionMeta>
@@ -2274,6 +2286,7 @@ const getMcpOutputSchema = (dataSchema: InputJsonSchema): InputJsonSchema => ({
properties: {
code: { type: "string" },
message: { type: "string" },
+ issues: semanticValidationIssuesJsonSchema,
},
required: ["code", "message"],
additionalProperties: true,
@@ -5669,141 +5682,36 @@ type ProjectSessionMcpErrorResult = {
content: [{ type: "text"; text: string }];
structuredContent: {
ok: false;
- error: {
- message: string;
- code: string;
- };
+ error: McpStructuredError;
meta: Record<string, never>;
};
};
-const getJsonSchemaExample = (
- schema: InputJsonSchema | undefined,
- depth = 0
-): unknown => {
- if (
- schema === undefined ||
- typeof schema !== "object" ||
- schema === null ||
- depth > 4
- ) {
- return {};
- }
- if ("default" in schema && schema.default !== undefined) {
- return schema.default;
- }
- if (
- "examples" in schema &&
- Array.isArray(schema.examples) &&
- schema.examples.length > 0
- ) {
- return schema.examples[0];
- }
- if ("const" in schema) {
- return schema.const;
- }
- if ("enum" in schema && Array.isArray(schema.enum)) {
- return schema.enum[0];
- }
- if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
- return getJsonSchemaExample(schema.anyOf[0] as InputJsonSchema, depth + 1);
- }
- if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
- return getJsonSchemaExample(schema.oneOf[0] as InputJsonSchema, depth + 1);
- }
- if ("allOf" in schema && Array.isArray(schema.allOf)) {
- const examples = schema.allOf.map((item) =>
- getJsonSchemaExample(item as InputJsonSchema, depth + 1)
- );
- return examples.every(
- (example) =>
- typeof example === "object" &&
- example !== null &&
- Array.isArray(example) === false
- )
- ? Object.assign({}, ...examples)
- : examples[0];
- }
- if (schema.type === "object") {
- const properties = getInputJsonSchemaProperties(schema) ?? {};
- const required = new Set(schema.required ?? []);
- const entries = Object.entries(properties).filter(([name]) =>
- required.has(name)
- );
- return Object.fromEntries(
- entries.map(([name, property]) => [
- name,
- getJsonSchemaExample(property as InputJsonSchema, depth + 1),
- ])
- );
- }
- if (schema.type === "array") {
- const minItems = schema.minItems ?? 0;
- return Array.from({ length: minItems }, () =>
- getJsonSchemaExample(schema.items as InputJsonSchema, depth + 1)
- );
- }
- if (schema.type === "number" || schema.type === "integer") {
- if (typeof schema.exclusiveMinimum === "number") {
- return schema.exclusiveMinimum + 1;
- }
- return schema.minimum ?? 0;
- }
- if (schema.type === "boolean") {
- return true;
- }
- if (schema.type === "string") {
- const formatExamples: Record<string, string> = {
- email: "[email protected]",
- uri: "https://example.com",
- url: "https://example.com",
- uuid: "00000000-0000-4000-8000-000000000000",
- date: "2026-01-01",
- "date-time": "2026-01-01T00:00:00.000Z",
- };
- const base =
- typeof schema.format === "string"
- ? (formatExamples[schema.format] ?? "string")
- : "string";
- return base.padEnd(schema.minLength ?? 0, "x");
- }
- return {};
-};
-
-const getZodErrorMessage = (
- error: z.ZodError,
- inputSchema: InputJsonSchema | undefined
-) => {
- const issues = error.issues
- .map((issue) => {
- const path = issue.path.join(".");
- return path === "" ? issue.message : `${path}: ${issue.message}`;
- })
- .join(", ");
- const example = getJsonSchemaExample(inputSchema);
- return `${issues}. Expected input shape example: ${JSON.stringify(example)}`;
-};
-
-const getZodFieldIssues = (error: z.ZodError) =>
- error.issues.map((issue) => ({
- path: issue.path.map(String),
- message: issue.message,
- }));
-
const toToolErrorResult = (
error: unknown,
getErrorCode: McpErrorCodeResolver | undefined,
inputSchema?: InputJsonSchema
): ProjectSessionMcpErrorResult => {
+ const structuredCode =
+ typeof error === "object" &&
+ error !== null &&
+ "code" in error &&
+ typeof error.code === "string"
+ ? error.code
+ : undefined;
const code =
error instanceof z.ZodError
? "INVALID_INPUT"
- : (getErrorCode?.(error) ?? "MCP_TOOL_FAILED");
+ : (getErrorCode?.(error) ?? structuredCode ?? "MCP_TOOL_FAILED");
+ const validationIssues =
+ error instanceof z.ZodError
+ ? getZodValidationIssues(error, inputSchema)
+ : getValidationIssues(error);
const message =
code === "PROJECT_SESSION_BUSY"
? projectSessionBusyMessage
: error instanceof z.ZodError
- ? getZodErrorMessage(error, inputSchema)
+ ? "Tool input is invalid."
: error instanceof Error
? error.message
: String(error);
@@ -5812,9 +5720,7 @@ const toToolErrorResult = (
error: {
message,
code,
- ...(error instanceof z.ZodError
- ? { issues: getZodFieldIssues(error) }
- : {}),
+ ...(validationIssues === undefined ? {} : { issues: validationIssues }),
},
meta: {},
};
diff --git a/packages/project-build/src/project-session.test.ts b/packages/project-build/src/project-session.test.ts
index ed766aefe7..a9e2373e6f 100644
--- a/packages/project-build/src/project-session.test.ts
+++ b/packages/project-build/src/project-session.test.ts
@@ -813,6 +813,32 @@ describe("project session", () => {
});
});
+ test("returns actionable validation issues from local runtime operations", async () => {
+ const storage = createStorage(createPersistedSnapshot());
+ const session = createSession({ storage, transport: createTransport() });
+
+ await session.initialize();
+ const result = await session.mutate("pages.update", {
+ pageId: "page-home",
+ values: { name: 42 },
+ });
+
+ expect(result.state.committed).toBe(false);
+ expect(result.diagnostics).toEqual([
+ expect.objectContaining({
+ code: "INVALID_INPUT",
+ issues: [
+ expect.objectContaining({
+ code: "invalid_type",
+ path: ["values", "name"],
+ constraint: "type:string",
+ example: "string",
+ }),
+ ],
+ }),
+ ]);
+ });
+
test("refreshes required namespaces and returns conflict diagnostic", async () => {
const storage = createStorage(createPersistedSnapshot());
const transport = createTransport();
diff --git a/packages/project-build/src/project-session.ts b/packages/project-build/src/project-session.ts
index 944e02027f..f4ac13869a 100644
--- a/packages/project-build/src/project-session.ts
+++ b/packages/project-build/src/project-session.ts
@@ -14,7 +14,11 @@ import {
builderRuntimeContext,
type BuilderRuntimeContext,
} from "./runtime/context";
-import { BuilderRuntimeError } from "./runtime/errors";
+import {
+ BuilderRuntimeError,
+ getValidationIssues,
+ type SemanticValidationIssue,
+} from "./runtime/errors";
import type { BuilderRuntimeMutation } from "./runtime/mutation";
import { executeBuilderRuntimeOperation } from "./runtime/registry";
import type { BuilderState } from "./state/builder-state";
@@ -36,6 +40,7 @@ export type ProjectSessionDiagnostic = {
level: ProjectSessionDiagnosticLevel;
code: string;
message: string;
+ issues?: readonly SemanticValidationIssue[];
details?: unknown;
};
@@ -440,12 +445,22 @@ export const redactProjectSessionValue = (value: unknown): unknown => {
return redacted;
};
-const errorDiagnostic = (error: unknown): ProjectSessionDiagnostic => ({
- level: "error",
- code: getProjectSessionErrorCode(error),
- message: error instanceof Error ? error.message : "Unknown error",
- details: redactProjectSessionValue(error),
-});
+const errorDiagnostic = (error: unknown): ProjectSessionDiagnostic => {
+ const issues = getValidationIssues(error);
+ return {
+ level: "error",
+ code: getProjectSessionErrorCode(error),
+ message: error instanceof Error ? error.message : "Unknown error",
+ ...(issues === undefined
+ ? {}
+ : {
+ issues: redactProjectSessionValue(
+ issues
+ ) as SemanticValidationIssue[],
+ }),
+ details: redactProjectSessionValue(error),
+ };
+};
const shouldRefreshPermissionsAfterError = (error: unknown) => {
const code = getProjectSessionErrorCode(error);
diff --git a/packages/project-build/src/runtime/assets.ts b/packages/project-build/src/runtime/assets.ts
index bea57b3b19..451c18ccfc 100644
--- a/packages/project-build/src/runtime/assets.ts
+++ b/packages/project-build/src/runtime/assets.ts
@@ -24,7 +24,11 @@ import type { BuilderPatchChange } from "../contracts/patch";
import type { BuilderState } from "../state/builder-state";
import type { CompactBuild } from "../types";
import type { ProjectSettings } from "../shared/project-settings";
-import { throwBuilderRuntimeError } from "./errors";
+import {
+ addZodValidationIssue,
+ getZodValidationIssueOptions,
+ throwBuilderRuntimeError,
+} from "./errors";
import { createRuntimeMutation } from "./mutation";
import {
collectFontFamiliesFromStyleValue,
@@ -67,9 +71,16 @@ export const assetUpdateInput = z.object({
.optional(),
description: z.union([z.string(), z.null()]).optional(),
})
- .refine((values) => Object.keys(values).length > 0, {
- message: "At least one asset field is required",
- }),
+ .refine(
+ (values) => Object.keys(values).length > 0,
+ getZodValidationIssueOptions({
+ code: "empty_asset_update",
+ path: [],
+ message: "At least one asset field is required",
+ constraint: "at_least_one_property",
+ example: { description: "A concise image description" },
+ })
+ ),
});
const imageDescriptionUpdate = z.union([
@@ -111,10 +122,11 @@ export const imageDescriptionsSetInput = z
const assetIds = new Set<string>();
updates.forEach(({ assetId }, index) => {
if (assetIds.has(assetId)) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
- path: ["updates", index, "assetId"],
+ addZodValidationIssue(context, {
+ code: "duplicate_asset_update",
+ path: ["updates", String(index), "assetId"],
message: "Each image asset may be updated only once.",
+ constraint: "unique_by:assetId",
});
}
assetIds.add(assetId);
diff --git a/packages/project-build/src/runtime/audit.test.ts b/packages/project-build/src/runtime/audit.test.ts
index f78756d641..f646a30e89 100644
--- a/packages/project-build/src/runtime/audit.test.ts
+++ b/packages/project-build/src/runtime/audit.test.ts
@@ -350,14 +350,11 @@ describe("project audit and analysis", () => {
});
test("rejects unknown audit input fields at the runtime boundary", () => {
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "project.audit",
- state,
- input: { unknown: true },
- context: { projectVersion: 1, createId: () => "unused" },
- })
- ).toThrow(/Unrecognized key/);
+ expectRuntimeValidationError(
+ "project.audit",
+ { unknown: true },
+ { constraint: "recognized_keys_only" }
+ );
});
test("filters audit scopes and severities independently", () => {
diff --git a/packages/project-build/src/runtime/components.test.ts b/packages/project-build/src/runtime/components.test.ts
index 13717bc5ac..470ef5a6ff 100644
--- a/packages/project-build/src/runtime/components.test.ts
+++ b/packages/project-build/src/runtime/components.test.ts
@@ -19,7 +19,9 @@ import {
insertComponent,
insertComponentInput,
insertFragment,
+ insertFragmentInput,
} from "./components";
+import { getZodValidationIssues } from "./errors";
import { getComponentTemplates } from "./component-templates";
import { createEmptyWebstudioFragment } from "./component-template";
import { isLikelyWebstudioJsxFragment, parseWebstudioJsxFragment } from "./jsx";
@@ -151,6 +153,27 @@ test("validates component ids with canonical instance schema", () => {
).toBe(false);
});
+test("explains the required parent for fragments with children", () => {
+ const result = insertFragmentInput.safeParse({
+ fragment: {
+ ...createEmptyWebstudioFragment(),
+ children: [{ type: "id", value: "child" }],
+ },
+ });
+ if (result.success) {
+ throw new Error("Expected fragment input to require a parent");
+ }
+
+ expect(getZodValidationIssues(result.error)).toEqual([
+ expect.objectContaining({
+ code: "missing_fragment_parent",
+ path: ["parentInstanceId"],
+ constraint: "required_when:fragment.children.length>0",
+ example: "parent-instance-id",
+ }),
+ ]);
+});
+
test("requires tag when inserting ws.element component", async () => {
const parent = createParent();
@@ -1463,6 +1486,20 @@ test("rejects module syntax in webstudio jsx fragments", async () => {
await expect(
parseWebstudioJsxFragment(`export const view = <$.Box />`)
).rejects.toThrow("Do not use import or export in JSX fragments");
+ await expect(
+ parseWebstudioJsxFragment(`import { Box } from "x"; <$.Box />`)
+ ).rejects.toMatchObject({
+ code: "INVALID_INPUT",
+ issues: [
+ expect.objectContaining({
+ code: "invalid_webstudio_jsx",
+ path: ["fragment"],
+ constraint: "declarative_jsx_without_modules",
+ example:
+ '<ws.element ws:tag="section"><ws.element ws:tag="h2">Title</ws.element></ws.element>',
+ }),
+ ],
+ });
});
test("rejects react fragment shorthand in webstudio jsx fragments", async () => {
diff --git a/packages/project-build/src/runtime/components.ts b/packages/project-build/src/runtime/components.ts
index 0ebcfd2186..0bfcb471e0 100644
--- a/packages/project-build/src/runtime/components.ts
+++ b/packages/project-build/src/runtime/components.ts
@@ -42,7 +42,7 @@ import {
import type { BuilderRuntimeContext } from "./context";
import { isFragmentContentModeCopyableProp } from "./content-mode-copy-policy";
import { findAvailableVariables } from "./data";
-import { throwBuilderRuntimeError } from "./errors";
+import { addZodValidationIssue, throwBuilderRuntimeError } from "./errors";
import { insertWebstudioFragmentCopy } from "./fragment";
import {
createInstanceAppendPayload,
@@ -87,10 +87,12 @@ export const insertFragmentInput = z
input.fragment.children.length > 0 &&
input.parentInstanceId === undefined
) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
+ addZodValidationIssue(context, {
+ code: "missing_fragment_parent",
path: ["parentInstanceId"],
message: "Required when inserting a fragment with children",
+ constraint: "required_when:fragment.children.length>0",
+ example: "parent-instance-id",
});
}
});
diff --git a/packages/project-build/src/runtime/data.ts b/packages/project-build/src/runtime/data.ts
index 9fd3362802..b7442519b4 100644
--- a/packages/project-build/src/runtime/data.ts
+++ b/packages/project-build/src/runtime/data.ts
@@ -44,10 +44,18 @@ import { createBuilderPatchPayloadFromImmerPatches } from "../state/patch";
import type { BuilderState } from "../state/builder-state";
import "../state/immer";
import type { BuilderRuntimeContext } from "./context";
-import { throwBuilderRuntimeError } from "./errors";
+import {
+ addZodValidationIssue,
+ formatValidationIssueMessages,
+ prefixValidationIssuePaths,
+ throwBuilderRuntimeError,
+ throwBuilderValidationError,
+ type SemanticValidationIssue,
+} from "./errors";
import { getStaticStringLiteral, replaceTextValue } from "./text-replacement";
import {
getNamedExpressionErrors,
+ getNamedExpressionValidationIssues,
hasExpressionDiagnostics,
} from "./expression-validation";
import { runtimeGeneratedIdInput } from "./generated-id-input";
@@ -1511,13 +1519,16 @@ export const findResource = (
const addExpressionIssues = (
context: z.RefinementCtx,
- errors: readonly string[]
+ issues: readonly SemanticValidationIssue[]
) => {
- for (const message of errors) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
- message,
- });
+ for (const issue of issues) {
+ addZodValidationIssue(
+ context,
+ issue,
+ issue.code === "invalid_resource_url"
+ ? { message: `${issue.path.join(".")}: ${issue.message}` }
+ : undefined
+ );
}
};
@@ -1563,8 +1574,14 @@ const resourceFieldsInputBase = resource.omit({ id: true }).extend({
export const resourceFieldsInput = resourceFieldsInputBase.superRefine(
(fields, context) => {
const normalizedFields = normalizeResourceFieldsInput(fields);
- addExpressionIssues(context, getResourceExpressionErrors(normalizedFields));
- addExpressionIssues(context, getResourceLiteralUrlErrors(normalizedFields));
+ addExpressionIssues(
+ context,
+ getResourceExpressionValidationIssues(normalizedFields)
+ );
+ addExpressionIssues(
+ context,
+ getResourceLiteralUrlValidationIssues(normalizedFields)
+ );
}
);
@@ -1572,8 +1589,14 @@ export const resourceFieldsUpdateInput = resourceFieldsInputBase
.partial()
.superRefine((fields, context) => {
const normalizedFields = normalizeResourceFieldsUpdateInput(fields);
- addExpressionIssues(context, getResourceExpressionErrors(normalizedFields));
- addExpressionIssues(context, getResourceLiteralUrlErrors(normalizedFields));
+ addExpressionIssues(
+ context,
+ getResourceExpressionValidationIssues(normalizedFields)
+ );
+ addExpressionIssues(
+ context,
+ getResourceLiteralUrlValidationIssues(normalizedFields)
+ );
});
const normalizeResourceExpressionInput = (
@@ -1638,10 +1661,12 @@ export const resourceCreateInput = z
input.exposeAsDataSource === true &&
input.scopeInstanceId === undefined
) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
+ addZodValidationIssue(context, {
+ code: "missing_resource_scope",
path: ["scopeInstanceId"],
message: "scopeInstanceId is required when exposeAsDataSource is true.",
+ constraint: "required_when:exposeAsDataSource=true",
+ example: "instance-id",
});
}
});
@@ -1835,12 +1860,12 @@ export const validateResourceBodyExpression = (
return typeof value === "string" ? "" : "Expected string in body";
};
-export const getResourceExpressionErrors = (
+const getResourceExpressionValidationIssues = (
fields: Partial<Pick<Resource, "url" | "body" | "headers" | "searchParams">>
) => {
- const errors: string[] = [];
+ const issues: SemanticValidationIssue[] = [];
const validate = (name: string, expression: string | undefined) => {
- errors.push(...getNamedExpressionErrors(name, expression));
+ issues.push(...getNamedExpressionValidationIssues(name, expression));
};
validate("url", fields.url);
validate("body", fields.body);
@@ -1850,12 +1875,19 @@ export const getResourceExpressionErrors = (
for (const [index, searchParam] of (fields.searchParams ?? []).entries()) {
validate(`searchParams.${index}.value`, searchParam.value);
}
- return errors;
+ return issues;
};
-const getResourceLiteralUrlErrors = (
+export const getResourceExpressionErrors = (
+ fields: Partial<Pick<Resource, "url" | "body" | "headers" | "searchParams">>
+) =>
+ formatValidationIssueMessages(getResourceExpressionValidationIssues(fields))
+ .split("\n")
+ .filter(Boolean);
+
+const getResourceLiteralUrlValidationIssues = (
fields: Partial<Pick<Resource, "url">>
-) => {
+): SemanticValidationIssue[] => {
if (fields.url === undefined || isLiteralExpression(fields.url) === false) {
return [];
}
@@ -1866,10 +1898,26 @@ const getResourceLiteralUrlErrors = (
return [];
}
if (typeof value !== "string") {
- return ["url: URL expects a string"];
+ return [
+ {
+ code: "invalid_resource_url",
+ path: ["url"],
+ message: "URL expects a string",
+ constraint: "absolute_or_root_relative_url",
+ example: "https://api.example.com/posts",
+ },
+ ];
}
if (value.length === 0) {
- return ["url: URL is required"];
+ return [
+ {
+ code: "invalid_resource_url",
+ path: ["url"],
+ message: "URL is required",
+ constraint: "absolute_or_root_relative_url",
+ example: "https://api.example.com/posts",
+ },
+ ];
}
if (isLocalResource(value)) {
return [];
@@ -1877,20 +1925,32 @@ const getResourceLiteralUrlErrors = (
try {
new URL(value);
} catch {
- return ["url: URL is invalid"];
+ return [
+ {
+ code: "invalid_resource_url",
+ path: ["url"],
+ message: "URL is invalid",
+ constraint: "absolute_or_root_relative_url",
+ example: "https://api.example.com/posts",
+ },
+ ];
}
return [];
};
const validateResourceFields = (
- fields: Partial<Pick<Resource, "url" | "body" | "headers" | "searchParams">>
+ fields: Partial<Pick<Resource, "url" | "body" | "headers" | "searchParams">>,
+ pathPrefix: readonly string[] = []
) => {
- const errors = [
- ...getResourceExpressionErrors(fields),
- ...getResourceLiteralUrlErrors(fields),
+ const issues = [
+ ...getResourceExpressionValidationIssues(fields),
+ ...getResourceLiteralUrlValidationIssues(fields),
];
- if (errors.length > 0) {
- return throwBuilderRuntimeError("BAD_REQUEST", errors.join("\n"));
+ if (issues.length > 0) {
+ return throwBuilderValidationError(
+ formatValidationIssueMessages(issues),
+ prefixValidationIssuePaths(issues, pathPrefix)
+ );
}
};
@@ -2346,7 +2406,7 @@ export const createResource = (
context: BuilderRuntimeContext
) => {
const resourceInput = normalizeResourceFieldsInput(input.resource);
- validateResourceFields(resourceInput);
+ validateResourceFields(resourceInput, ["resource"]);
const build = getRequiredBuildData(state);
const resourceId = context.createId();
const exposeAsDataSource =
@@ -2440,7 +2500,7 @@ export const updateResource = (
context: BuilderRuntimeContext
) => {
const values = normalizeResourceFieldsUpdateInput(input.values);
- validateResourceFields(values);
+ validateResourceFields(values, ["values"]);
const build = getRequiredBuildData(state);
const resource = findResource(build.resources, input.resourceId);
if (resource === undefined) {
@@ -2565,7 +2625,10 @@ export const replaceResourceText = (
continue;
}
if (field === "url") {
- validateResourceFields({ url: JSON.stringify(after) });
+ validateResourceFields({ url: JSON.stringify(after) }, [
+ "resources",
+ resource.id,
+ ]);
}
matches.push({ resourceId: resource.id, field, before, after });
}
@@ -2612,7 +2675,7 @@ export const upsertResource = (
context: BuilderRuntimeContext
) => {
const resourceInput = normalizeResourceFieldsInput(input.resource);
- validateResourceFields(resourceInput);
+ validateResourceFields(resourceInput, ["resource"]);
const build = getRequiredBuildData(state);
if (
input.resourceId !== undefined &&
@@ -2682,7 +2745,7 @@ export const upsertResourceProp = (
context: BuilderRuntimeContext
) => {
const resourceInput = normalizeResourceFieldsInput(input.resource);
- validateResourceFields(resourceInput);
+ validateResourceFields(resourceInput, ["resource"]);
const build = getRequiredBuildData(state);
if (
build.instances.some((instance) => instance.id === input.instanceId) ===
diff --git a/packages/project-build/src/runtime/errors.test.ts b/packages/project-build/src/runtime/errors.test.ts
index 1da1c8c390..4191121626 100644
--- a/packages/project-build/src/runtime/errors.test.ts
+++ b/packages/project-build/src/runtime/errors.test.ts
@@ -1,5 +1,16 @@
+import { getInputSchemaMetadata } from "../contracts/input-schema";
import { expect, test } from "vitest";
-import { BuilderRuntimeError, throwBuilderRuntimeError } from "./errors";
+import { z } from "zod";
+import {
+ addZodValidationIssue,
+ BuilderRuntimeError,
+ formatValidationIssues,
+ getZodValidationIssues,
+ getValidationIssues,
+ sanitizeValidationDetail,
+ throwBuilderRuntimeError,
+ throwBuilderValidationError,
+} from "./errors";
test("creates runtime errors with stable code and name", () => {
const error = new BuilderRuntimeError("BAD_REQUEST", "Invalid input");
@@ -18,3 +29,185 @@ test("throws runtime errors", () => {
"Changed"
);
});
+
+test("creates actionable issues from zod constraints", () => {
+ const schema = z.object({
+ email: z.email(),
+ items: z.array(z.object({ count: z.number().int().min(1) })).min(1),
+ });
+ const result = schema.safeParse({
+ email: "invalid",
+ items: [{ count: 0 }],
+ });
+ if (result.success) {
+ throw new Error("Expected test input to be invalid");
+ }
+
+ const issues = getZodValidationIssues(
+ result.error,
+ getInputSchemaMetadata(schema).inputJsonSchema
+ );
+
+ expect(issues).toEqual([
+ expect.objectContaining({
+ code: "invalid_format",
+ path: ["email"],
+ constraint: "format:email",
+ example: "[email protected]",
+ }),
+ expect.objectContaining({
+ code: "too_small",
+ path: ["items", "0", "count"],
+ constraint: "number:minimum:1",
+ example: 1,
+ }),
+ ]);
+ expect(formatValidationIssues(issues)).toContain("items.0.count: Too small");
+});
+
+test("preserves semantic codes and identifies each unknown key", () => {
+ const schema = z
+ .object({
+ expression: z.string().superRefine((_value, context) => {
+ addZodValidationIssue(context, {
+ code: "invalid_expression",
+ path: [],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: "item.title",
+ });
+ }),
+ })
+ .strict();
+ const result = schema.safeParse({ expression: "bad", unexpected: true });
+ if (result.success) {
+ throw new Error("Expected test input to be invalid");
+ }
+
+ expect(getZodValidationIssues(result.error)).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "invalid_expression",
+ path: ["expression"],
+ }),
+ expect.objectContaining({
+ code: "unrecognized_keys",
+ path: ["unexpected"],
+ constraint: "recognized_keys_only",
+ }),
+ ])
+ );
+});
+
+test("separates legacy display text from the structured issue message", () => {
+ const schema = z.string().superRefine((_value, context) => {
+ addZodValidationIssue(
+ context,
+ {
+ code: "invalid_resource_url",
+ path: [],
+ message: "URL is invalid",
+ constraint: "absolute_or_root_relative_url",
+ },
+ { message: "url: URL is invalid" }
+ );
+ });
+ const result = schema.safeParse("invalid");
+ if (result.success) {
+ throw new Error("Expected test input to be invalid");
+ }
+
+ expect(result.error.issues[0]?.message).toBe("url: URL is invalid");
+ expect(getZodValidationIssues(result.error)).toEqual([
+ expect.objectContaining({
+ code: "invalid_resource_url",
+ message: "URL is invalid",
+ }),
+ ]);
+});
+
+test("reports the closest union branch with its complete field path", () => {
+ const schema = z.object({
+ binding: z.union([
+ z.object({ type: z.literal("expression"), value: z.string() }),
+ z.object({ type: z.literal("resource"), resourceId: z.string() }),
+ ]),
+ });
+ const result = schema.safeParse({
+ binding: { type: "resource", resourceId: 42 },
+ });
+ if (result.success) {
+ throw new Error("Expected test input to be invalid");
+ }
+
+ expect(
+ getZodValidationIssues(
+ result.error,
+ getInputSchemaMetadata(schema).inputJsonSchema
+ )
+ ).toEqual([
+ expect.objectContaining({
+ code: "invalid_type",
+ path: ["binding", "resourceId"],
+ constraint: "type:string",
+ example: "string",
+ }),
+ ]);
+});
+
+test("preserves semantic issue metadata on runtime errors", () => {
+ expect(() =>
+ throwBuilderValidationError("Invalid title", [
+ {
+ code: "invalid_expression",
+ path: ["values", "title"],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: 'pageTitle ?? "Pricing"',
+ detail: "Unexpected token",
+ },
+ ])
+ ).toThrow(
+ expect.objectContaining({
+ code: "INVALID_INPUT",
+ issues: [
+ expect.objectContaining({
+ path: ["values", "title"],
+ detail: "Unexpected token",
+ }),
+ ],
+ })
+ );
+});
+
+test("removes stack frames and credentials from parser details", () => {
+ expect(
+ sanitizeValidationDetail(
+ 'Unexpected token at 1:4\n at parse (/private/parser.ts:10:2)\nauthToken=private-value password="two private words" Authorization: "Bearer private header"'
+ )
+ ).toBe(
+ 'Unexpected token at 1:4\nauthToken=[redacted] password="[redacted]" Authorization: "[redacted]"'
+ );
+});
+
+test("reads validation issues from serialized API error data", () => {
+ expect(
+ getValidationIssues({
+ data: {
+ issues: [
+ {
+ code: "invalid_type",
+ path: ["name"],
+ message: "Expected string",
+ constraint: "type:string",
+ },
+ ],
+ },
+ })
+ ).toEqual([
+ expect.objectContaining({
+ code: "invalid_type",
+ path: ["name"],
+ }),
+ ]);
+});
diff --git a/packages/project-build/src/runtime/errors.ts b/packages/project-build/src/runtime/errors.ts
index ecddd04d79..941b9b1a00 100644
--- a/packages/project-build/src/runtime/errors.ts
+++ b/packages/project-build/src/runtime/errors.ts
@@ -1,18 +1,391 @@
-export type BuilderRuntimeErrorCode = "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT";
+import {
+ getInputJsonSchemaProperties,
+ type InputJsonSchema,
+} from "@webstudio-is/sdk";
+import { z } from "zod";
+import { getInputSchemaMetadata } from "../contracts/input-schema";
+
+export type BuilderRuntimeErrorCode =
+ | "BAD_REQUEST"
+ | "INVALID_INPUT"
+ | "NOT_FOUND"
+ | "CONFLICT";
+
+const semanticValidationIssueSchema = z.object({
+ code: z.string(),
+ path: z.array(z.string()),
+ message: z.string(),
+ constraint: z.string(),
+ example: z.unknown().optional(),
+ detail: z.string().optional(),
+});
+const semanticValidationIssuesSchema = z.array(semanticValidationIssueSchema);
+
+export type SemanticValidationIssue = z.infer<
+ typeof semanticValidationIssueSchema
+>;
+
+export const semanticValidationIssuesJsonSchema = getInputSchemaMetadata(
+ semanticValidationIssuesSchema
+).inputJsonSchema;
+
+const quotedSensitiveValidationDetailPattern =
+ /(authorization|authToken|password|secret|token)(["']?\s*[:=]\s*)(["'])[^"']*\3/gi;
+const unquotedSensitiveValidationDetailPattern =
+ /(authorization|authToken|password|secret|token)(["']?\s*[:=]\s*)(?!["'])[^,\s}]+/gi;
+const sensitiveValidationQueryPattern =
+ /([?&](?:authToken|password|secret|token)=)[^&\s]+/gi;
+
+export const sanitizeValidationDetail = (detail: string) =>
+ detail
+ .split("\n")
+ .filter((line) => /^\s*at\s/.test(line) === false)
+ .join("\n")
+ .replace(quotedSensitiveValidationDetailPattern, "$1$2$3[redacted]$3")
+ .replace(unquotedSensitiveValidationDetailPattern, "$1$2[redacted]")
+ .replace(/Bearer\s+\S+/gi, "Bearer [redacted]")
+ .replace(sensitiveValidationQueryPattern, "$1[redacted]");
+
+const sanitizeValidationIssues = (
+ issues: readonly SemanticValidationIssue[]
+): SemanticValidationIssue[] =>
+ issues.map((issue) => ({
+ ...issue,
+ ...(issue.detail === undefined
+ ? {}
+ : { detail: sanitizeValidationDetail(issue.detail) }),
+ }));
+
+type BuilderRuntimeErrorOptions = {
+ issues?: readonly SemanticValidationIssue[];
+};
export class BuilderRuntimeError extends Error {
code: BuilderRuntimeErrorCode;
+ issues?: readonly SemanticValidationIssue[];
- constructor(code: BuilderRuntimeErrorCode, message: string) {
+ constructor(
+ code: BuilderRuntimeErrorCode,
+ message: string,
+ options: BuilderRuntimeErrorOptions = {}
+ ) {
super(message);
this.name = "BuilderRuntimeError";
this.code = code;
+ this.issues = options.issues;
}
}
export const throwBuilderRuntimeError = (
code: BuilderRuntimeErrorCode,
- message: string
+ message: string,
+ options?: BuilderRuntimeErrorOptions
): never => {
- throw new BuilderRuntimeError(code, message);
+ throw new BuilderRuntimeError(code, message, options);
+};
+
+export const throwBuilderValidationError = (
+ message: string,
+ issues: readonly SemanticValidationIssue[]
+): never =>
+ throwBuilderRuntimeError("INVALID_INPUT", message, {
+ issues,
+ });
+
+const getJsonSchemaAtPath = (
+ schema: InputJsonSchema | undefined,
+ path: readonly PropertyKey[]
+) => {
+ let current = schema;
+ for (const segment of path) {
+ if (current === undefined) {
+ return;
+ }
+ if (current.type === "array" && typeof segment === "number") {
+ current = current.items as InputJsonSchema | undefined;
+ continue;
+ }
+ const properties = getInputJsonSchemaProperties(current);
+ current = properties?.[String(segment)] as InputJsonSchema | undefined;
+ }
+ return current;
+};
+
+export const getJsonSchemaExample = (
+ schema: InputJsonSchema | undefined,
+ depth = 0
+): unknown => {
+ if (schema === undefined || depth > 4) {
+ return undefined;
+ }
+ if (schema.default !== undefined) {
+ return schema.default;
+ }
+ if (Array.isArray(schema.examples) && schema.examples.length > 0) {
+ return schema.examples[0];
+ }
+ if ("const" in schema) {
+ return schema.const;
+ }
+ if (Array.isArray(schema.enum)) {
+ return schema.enum[0];
+ }
+ if (Array.isArray(schema.anyOf)) {
+ return getJsonSchemaExample(schema.anyOf[0] as InputJsonSchema, depth + 1);
+ }
+ if (Array.isArray(schema.oneOf)) {
+ return getJsonSchemaExample(schema.oneOf[0] as InputJsonSchema, depth + 1);
+ }
+ if (Array.isArray(schema.allOf)) {
+ const examples = schema.allOf.map((item) =>
+ getJsonSchemaExample(item as InputJsonSchema, depth + 1)
+ );
+ return examples.every(
+ (example) =>
+ typeof example === "object" &&
+ example !== null &&
+ Array.isArray(example) === false
+ )
+ ? Object.assign({}, ...examples)
+ : examples[0];
+ }
+ if (schema.type === "object") {
+ const properties = getInputJsonSchemaProperties(schema) ?? {};
+ const required = new Set(schema.required ?? []);
+ return Object.fromEntries(
+ Object.entries(properties)
+ .filter(([name]) => required.has(name))
+ .map(([name, property]) => [
+ name,
+ getJsonSchemaExample(property as InputJsonSchema, depth + 1),
+ ])
+ );
+ }
+ if (schema.type === "array") {
+ return Array.from({ length: schema.minItems ?? 0 }, () =>
+ getJsonSchemaExample(schema.items as InputJsonSchema, depth + 1)
+ );
+ }
+ if (schema.type === "number" || schema.type === "integer") {
+ return typeof schema.exclusiveMinimum === "number"
+ ? schema.exclusiveMinimum + 1
+ : (schema.minimum ?? 0);
+ }
+ if (schema.type === "boolean") {
+ return true;
+ }
+ if (schema.type === "string") {
+ const formatExamples: Record<string, string> = {
+ email: "[email protected]",
+ uri: "https://example.com",
+ url: "https://example.com",
+ uuid: "00000000-0000-4000-8000-000000000000",
+ date: "2026-01-01",
+ "date-time": "2026-01-01T00:00:00.000Z",
+ };
+ const base =
+ typeof schema.format === "string"
+ ? (formatExamples[schema.format] ?? "string")
+ : "string";
+ return base.padEnd(schema.minLength ?? 0, "x");
+ }
+};
+
+const getZodIssueConstraint = (issue: z.core.$ZodIssue) => {
+ if (
+ "params" in issue &&
+ typeof issue.params === "object" &&
+ issue.params !== null &&
+ "constraint" in issue.params &&
+ typeof issue.params.constraint === "string"
+ ) {
+ return issue.params.constraint;
+ }
+ if (issue.code === "invalid_type") {
+ return `type:${issue.expected}`;
+ }
+ if (issue.code === "unrecognized_keys") {
+ return "recognized_keys_only";
+ }
+ if (issue.code === "invalid_value") {
+ return `one_of:${JSON.stringify(issue.values)}`;
+ }
+ if (issue.code === "too_small") {
+ return `${issue.origin}:minimum:${String(issue.minimum)}`;
+ }
+ if (issue.code === "too_big") {
+ return `${issue.origin}:maximum:${String(issue.maximum)}`;
+ }
+ if (issue.code === "invalid_format") {
+ return `format:${issue.format}`;
+ }
+ return issue.code;
+};
+
+const flattenZodIssue = (
+ issue: z.core.$ZodIssue,
+ parentPath: readonly PropertyKey[] = []
+): z.core.$ZodIssue[] => {
+ const path = [...parentPath, ...issue.path];
+ if (issue.code !== "invalid_union" || issue.errors.length === 0) {
+ return [{ ...issue, path }];
+ }
+ const closestBranch = issue.errors.reduce((closest, branch) =>
+ branch.length < closest.length ? branch : closest
+ );
+ return closestBranch.flatMap((nestedIssue) =>
+ flattenZodIssue(nestedIssue, path)
+ );
+};
+
+export const getZodValidationIssues = (
+ error: z.ZodError,
+ inputSchema?: InputJsonSchema
+): SemanticValidationIssue[] =>
+ error.issues
+ .flatMap((issue) => flattenZodIssue(issue))
+ .flatMap((issue) => {
+ const params =
+ "params" in issue &&
+ typeof issue.params === "object" &&
+ issue.params !== null
+ ? issue.params
+ : undefined;
+ const example =
+ issue.code === "unrecognized_keys"
+ ? undefined
+ : params !== undefined && "example" in params
+ ? params.example
+ : getJsonSchemaExample(
+ getJsonSchemaAtPath(inputSchema, issue.path)
+ );
+ const detail =
+ params !== undefined &&
+ "detail" in params &&
+ typeof params.detail === "string"
+ ? params.detail
+ : undefined;
+ const semanticCode =
+ params !== undefined &&
+ "semanticCode" in params &&
+ typeof params.semanticCode === "string"
+ ? params.semanticCode
+ : issue.code;
+ const message =
+ params !== undefined &&
+ "semanticMessage" in params &&
+ typeof params.semanticMessage === "string"
+ ? params.semanticMessage
+ : issue.message;
+ const createIssue = (path: PropertyKey[]): SemanticValidationIssue => ({
+ code: semanticCode,
+ path: path.map(String),
+ message,
+ constraint: getZodIssueConstraint(issue),
+ ...(example === undefined ? {} : { example }),
+ ...(detail === undefined
+ ? {}
+ : { detail: sanitizeValidationDetail(detail) }),
+ });
+ if (issue.code === "unrecognized_keys") {
+ return issue.keys.map((key) => createIssue([...issue.path, key]));
+ }
+ return [createIssue(issue.path)];
+ });
+
+export const getZodValidationIssueOptions = (
+ issue: SemanticValidationIssue,
+ options: { message?: string } = {}
+) => ({
+ path: issue.path,
+ message: options.message ?? issue.message,
+ params: {
+ semanticCode: issue.code,
+ ...(options.message === undefined || options.message === issue.message
+ ? {}
+ : { semanticMessage: issue.message }),
+ constraint: issue.constraint,
+ ...(issue.example === undefined ? {} : { example: issue.example }),
+ ...(issue.detail === undefined ? {} : { detail: issue.detail }),
+ },
+});
+
+export const addZodValidationIssue = (
+ context: z.RefinementCtx,
+ issue: SemanticValidationIssue,
+ options: { message?: string } = {}
+) => {
+ context.addIssue({
+ code: "custom",
+ ...getZodValidationIssueOptions(issue, options),
+ });
+};
+
+export const formatValidationIssues = (
+ issues: readonly SemanticValidationIssue[]
+) =>
+ issues
+ .map((issue) => {
+ const path = issue.path.length === 0 ? "input" : issue.path.join(".");
+ const message = issue.message.replace(/[.\s]+$/, "");
+ const example =
+ issue.example === undefined
+ ? ""
+ : ` Example: ${JSON.stringify(issue.example)}.`;
+ const detail =
+ issue.detail === undefined
+ ? ""
+ : ` Detail: ${sanitizeValidationDetail(issue.detail)}`;
+ return `${path}: ${message} (${issue.constraint}).${example}${detail}`;
+ })
+ .join("\n");
+
+export const formatValidationIssueMessages = (
+ issues: readonly SemanticValidationIssue[]
+) =>
+ issues
+ .map((issue) => {
+ const path = issue.path.length === 0 ? "input" : issue.path.join(".");
+ const detail =
+ issue.detail === undefined
+ ? ""
+ : `: ${sanitizeValidationDetail(issue.detail)}`;
+ return `${path}: ${issue.message}${detail}`;
+ })
+ .join("\n");
+
+export const prefixValidationIssuePaths = (
+ issues: readonly SemanticValidationIssue[],
+ prefix: readonly string[]
+): SemanticValidationIssue[] =>
+ prefix.length === 0
+ ? [...issues]
+ : issues.map((issue) => ({
+ ...issue,
+ path: [...prefix, ...issue.path],
+ }));
+
+export const getValidationIssues = (error: unknown) => {
+ if (error instanceof BuilderRuntimeError) {
+ return error.issues === undefined
+ ? undefined
+ : sanitizeValidationIssues(error.issues);
+ }
+ if (error instanceof z.ZodError) {
+ return getZodValidationIssues(error);
+ }
+ if (typeof error === "object" && error !== null) {
+ const directIssues = "issues" in error ? error.issues : undefined;
+ const data = "data" in error ? error.data : undefined;
+ const nestedIssues =
+ typeof data === "object" && data !== null && "issues" in data
+ ? data.issues
+ : undefined;
+ const result = semanticValidationIssuesSchema.safeParse(
+ directIssues ?? nestedIssues
+ );
+ if (result.success) {
+ return sanitizeValidationIssues(result.data);
+ }
+ }
};
diff --git a/packages/project-build/src/runtime/expression-validation.ts b/packages/project-build/src/runtime/expression-validation.ts
index 909bb6393e..5d3e2d9239 100644
--- a/packages/project-build/src/runtime/expression-validation.ts
+++ b/packages/project-build/src/runtime/expression-validation.ts
@@ -1,4 +1,5 @@
import { lintExpression } from "@webstudio-is/sdk";
+import type { SemanticValidationIssue } from "./errors";
export const getExpressionErrors = (expression: string) =>
lintExpression({ expression })
@@ -16,17 +17,38 @@ export const hasExpressionDiagnostics = (
options: Parameters<typeof lintExpression>[0]
) => lintExpression(options).length > 0;
-export const getNamedExpressionErrors = (
+export const getNamedExpressionValidationIssues = (
name: string,
expression: string | undefined,
- options: { hint?: string } = {}
-) => {
+ options: { hint?: string; example?: string } = {}
+): SemanticValidationIssue[] => {
if (expression === undefined) {
return [];
}
- return getExpressionErrors(expression).map((message) =>
- [name, "Invalid expression", options.hint, `Parser detail: ${message}`]
+ return getExpressionErrors(expression).map((detail) => ({
+ code: "invalid_expression",
+ path: name.split("."),
+ message: ["Invalid Webstudio expression", options.hint]
+ .filter(Boolean)
+ .join(": "),
+ constraint: "valid_webstudio_expression",
+ example: options.example ?? "item.title",
+ detail,
+ }));
+};
+
+export const getNamedExpressionErrors = (
+ name: string,
+ expression: string | undefined,
+ options: { hint?: string } = {}
+) =>
+ getNamedExpressionValidationIssues(name, expression, options).map((issue) =>
+ [
+ name,
+ "Invalid expression",
+ options.hint,
+ issue.detail === undefined ? undefined : `Parser detail: ${issue.detail}`,
+ ]
.filter(Boolean)
.join(": ")
);
-};
diff --git a/packages/project-build/src/runtime/instances.ts b/packages/project-build/src/runtime/instances.ts
index 512c513364..96dad62e09 100644
--- a/packages/project-build/src/runtime/instances.ts
+++ b/packages/project-build/src/runtime/instances.ts
@@ -22,7 +22,11 @@ import {
} from "../contracts/patch";
import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
-import { throwBuilderRuntimeError } from "./errors";
+import {
+ getZodValidationIssueOptions,
+ throwBuilderRuntimeError,
+ throwBuilderValidationError,
+} from "./errors";
import { replaceTextValue } from "./text-replacement";
import { getExpressionErrors } from "./expression-validation";
import { createRuntimeMutation } from "./mutation";
@@ -89,7 +93,13 @@ export const moveInstancesInput = z.object({
.refine(
({ insertIndex, position }) =>
insertIndex === undefined || position === undefined,
- { message: "Use either insertIndex or position, not both." }
+ getZodValidationIssueOptions({
+ code: "conflicting_move_position",
+ path: ["position"],
+ message: "Use either insertIndex or position, not both.",
+ constraint: "mutually_exclusive_with:insertIndex",
+ example: "end",
+ })
)
)
.min(1)
@@ -3309,6 +3319,19 @@ export const getTextContentErrors = ({
return getExpressionErrors(value);
};
+const throwTextExpressionValidationError = (errors: readonly string[]): never =>
+ throwBuilderValidationError(
+ errors.join("\n"),
+ errors.map((detail) => ({
+ code: "invalid_expression",
+ path: ["text"],
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: "item.title",
+ detail,
+ }))
+ );
+
export const setTextContentMutable = (
instance: Instance,
type: TextContentChild["type"],
@@ -3622,7 +3645,7 @@ export const updateTextInstance = (
const mode = input.mode ?? "text";
const errors = getTextContentErrors({ type: mode, value: input.text });
if (errors.length > 0) {
- return throwBuilderRuntimeError("BAD_REQUEST", errors.join("\n"));
+ return throwTextExpressionValidationError(errors);
}
const mutationResult = {
instanceId: input.instanceId,
@@ -3744,7 +3767,7 @@ export const setTextContent = (
value: input.text,
});
if (errors.length > 0) {
- return throwBuilderRuntimeError("BAD_REQUEST", errors.join("\n"));
+ return throwTextExpressionValidationError(errors);
}
const child = createTextContentChild({
diff --git a/packages/project-build/src/runtime/jsx/errors.ts b/packages/project-build/src/runtime/jsx/errors.ts
index 736e386700..ac2dc3d8db 100644
--- a/packages/project-build/src/runtime/jsx/errors.ts
+++ b/packages/project-build/src/runtime/jsx/errors.ts
@@ -1,3 +1,8 @@
+import {
+ sanitizeValidationDetail,
+ throwBuilderValidationError,
+} from "../errors";
+
export const getErrorMessage = (error: unknown) => {
if (
typeof error === "object" &&
@@ -9,3 +14,22 @@ export const getErrorMessage = (error: unknown) => {
}
return String(error);
};
+
+export const throwWebstudioJsxValidationError = (
+ message: string,
+ constraint: string,
+ detail?: string
+): never =>
+ throwBuilderValidationError(sanitizeValidationDetail(message), [
+ {
+ code: "invalid_webstudio_jsx",
+ path: ["fragment"],
+ message: "Invalid Webstudio JSX fragment",
+ constraint,
+ example:
+ '<ws.element ws:tag="section"><ws.element ws:tag="h2">Title</ws.element></ws.element>',
+ ...(detail === undefined
+ ? {}
+ : { detail: sanitizeValidationDetail(detail) }),
+ },
+ ]);
diff --git a/packages/project-build/src/runtime/jsx/evaluate.server.ts b/packages/project-build/src/runtime/jsx/evaluate.server.ts
index 75ca3dd5b4..e213c5fc56 100644
--- a/packages/project-build/src/runtime/jsx/evaluate.server.ts
+++ b/packages/project-build/src/runtime/jsx/evaluate.server.ts
@@ -1,8 +1,7 @@
import { runInNewContext } from "node:vm";
import { transform } from "esbuild";
import { createElement, Fragment } from "react";
-import { throwBuilderRuntimeError } from "../errors";
-import { getErrorMessage } from "./errors";
+import { getErrorMessage, throwWebstudioJsxValidationError } from "./errors";
type EvaluateJsxOptions = {
source: string;
@@ -35,7 +34,11 @@ export const evaluateJsx = async <Result>({
});
code = result.code;
} catch (error) {
- return throwBuilderRuntimeError("BAD_REQUEST", parseErrorMessage(error));
+ return throwWebstudioJsxValidationError(
+ parseErrorMessage(error),
+ "valid_webstudio_jsx_syntax",
+ getErrorMessage(error)
+ );
}
const exports: { default?: Result } = {};
@@ -57,14 +60,18 @@ export const evaluateJsx = async <Result>({
}
);
} catch (error) {
- return throwBuilderRuntimeError(
- "BAD_REQUEST",
- evaluationErrorMessage(error)
+ return throwWebstudioJsxValidationError(
+ evaluationErrorMessage(error),
+ "valid_declarative_webstudio_jsx",
+ getErrorMessage(error)
);
}
if (exports.default === undefined) {
- return throwBuilderRuntimeError("BAD_REQUEST", missingResultMessage);
+ return throwWebstudioJsxValidationError(
+ missingResultMessage,
+ "webstudio_jsx_fragment_produces_data"
+ );
}
return exports.default;
diff --git a/packages/project-build/src/runtime/jsx/syntax.ts b/packages/project-build/src/runtime/jsx/syntax.ts
index b68526efe0..48fbe50b8f 100644
--- a/packages/project-build/src/runtime/jsx/syntax.ts
+++ b/packages/project-build/src/runtime/jsx/syntax.ts
@@ -1,8 +1,7 @@
import { Parser } from "acorn";
import jsx from "acorn-jsx";
-import { throwBuilderRuntimeError } from "../errors";
import { webstudioJsxFragmentBuiltInHelpers } from "./bindings";
-import { getErrorMessage } from "./errors";
+import { getErrorMessage, throwWebstudioJsxValidationError } from "./errors";
const JsxParser = Parser.extend(jsx());
@@ -197,18 +196,19 @@ const hasModuleSyntax = (source: string) => {
export const inspectWebstudioJsxFragmentSyntax = (source: string) => {
if (hasModuleSyntax(source)) {
- return throwBuilderRuntimeError(
- "BAD_REQUEST",
- `Do not use import or export in JSX fragments. Use the built-in ${webstudioJsxFragmentBuiltInHelpers} helpers.`
+ return throwWebstudioJsxValidationError(
+ `Do not use import or export in JSX fragments. Use the built-in ${webstudioJsxFragmentBuiltInHelpers} helpers.`,
+ "declarative_jsx_without_modules"
);
}
let ast: AstNode;
try {
ast = parseWebstudioJsxFragmentExpression(source);
} catch (error) {
- return throwBuilderRuntimeError(
- "BAD_REQUEST",
- `Could not parse JSX fragment. Pass Webstudio JSX such as <$.Box><$.Heading>Title</$.Heading></$.Box>. ${getErrorMessage(error)}`
+ return throwWebstudioJsxValidationError(
+ `Could not parse JSX fragment. Pass Webstudio JSX such as <$.Box><$.Heading>Title</$.Heading></$.Box>. ${getErrorMessage(error)}`,
+ "valid_webstudio_jsx_syntax",
+ getErrorMessage(error)
);
}
const error = visitAst(ast, (node, context) => {
@@ -228,6 +228,9 @@ export const inspectWebstudioJsxFragmentSyntax = (source: string) => {
}
});
if (error !== undefined) {
- return throwBuilderRuntimeError("BAD_REQUEST", error);
+ return throwWebstudioJsxValidationError(
+ error,
+ "declarative_webstudio_jsx_only"
+ );
}
};
diff --git a/packages/project-build/src/runtime/page-selector.ts b/packages/project-build/src/runtime/page-selector.ts
index 82e453a6c3..06c55aafaa 100644
--- a/packages/project-build/src/runtime/page-selector.ts
+++ b/packages/project-build/src/runtime/page-selector.ts
@@ -1,14 +1,17 @@
import { z } from "zod";
+import { addZodValidationIssue } from "./errors";
export const validatePageSelector = (
input: { pageId?: string; pagePath?: string },
context: z.RefinementCtx
) => {
if (input.pageId !== undefined && input.pagePath !== undefined) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
+ addZodValidationIssue(context, {
+ code: "mutually_exclusive_fields",
path: ["pagePath"],
message: "pageId and pagePath are mutually exclusive",
+ constraint: "use_page_id_or_page_path",
+ example: "/pricing",
});
}
};
diff --git a/packages/project-build/src/runtime/pages.test.ts b/packages/project-build/src/runtime/pages.test.ts
index 792e6688a9..185e2c84f7 100644
--- a/packages/project-build/src/runtime/pages.test.ts
+++ b/packages/project-build/src/runtime/pages.test.ts
@@ -11,6 +11,7 @@ import {
} from "@webstudio-is/sdk";
import { createBuilderStateFromSnapshot } from "../state/adapters";
import { createRootFolder } from "../shared/pages-utils";
+import { getZodValidationIssues } from "./errors";
import {
createFolderCreatePayload,
createFolderDeletePayload,
@@ -552,13 +553,22 @@ test("validates page general settings inputs", () => {
redirect: "",
documentType: "html",
});
- expect(
- pageGeneralSettingsInput.safeParse({
- name: "Pricing",
- path: "/pricing",
- status: 999,
- }).success
- ).toBe(false);
+ const invalidStatus = pageGeneralSettingsInput.safeParse({
+ name: "Pricing",
+ path: "/pricing",
+ status: 999,
+ });
+ expect(invalidStatus.success).toBe(false);
+ if (invalidStatus.success === false) {
+ expect(getZodValidationIssues(invalidStatus.error)).toEqual([
+ expect.objectContaining({
+ code: "invalid_page_status",
+ path: ["status"],
+ constraint: "http_status:200-599",
+ example: 200,
+ }),
+ ]);
+ }
expect(
pageGeneralSettingsInput.safeParse({
name: "Pricing",
@@ -599,10 +609,21 @@ test("validates page search settings inputs", () => {
expect(
pageSearchSettingsInput.safeParse({ title: "D", language: "en-US" }).success
).toBe(false);
- expect(
- pageSearchSettingsInput.safeParse({ title: "Docs", language: "not locale" })
- .success
- ).toBe(false);
+ const invalidLanguage = pageSearchSettingsInput.safeParse({
+ title: "Docs",
+ language: "not locale",
+ });
+ expect(invalidLanguage.success).toBe(false);
+ if (invalidLanguage.success === false) {
+ expect(getZodValidationIssues(invalidLanguage.error)).toEqual([
+ expect.objectContaining({
+ code: "invalid_page_language",
+ path: ["language"],
+ constraint: "bcp_47_language_tag",
+ example: "en-US",
+ }),
+ ]);
+ }
});
test("validates page template settings inputs", () => {
diff --git a/packages/project-build/src/runtime/pages.ts b/packages/project-build/src/runtime/pages.ts
index b86d98d811..08619388a2 100644
--- a/packages/project-build/src/runtime/pages.ts
+++ b/packages/project-build/src/runtime/pages.ts
@@ -33,8 +33,15 @@ import type { BuilderState } from "../state/builder-state";
import type { BuilderRuntimeContext } from "./context";
import { validateBasicAuthCredentials } from "./auth";
import { computeExpression } from "./data";
-import { throwBuilderRuntimeError } from "./errors";
-import { getNamedExpressionErrors } from "./expression-validation";
+import {
+ formatValidationIssueMessages,
+ getZodValidationIssueOptions,
+ prefixValidationIssuePaths,
+ throwBuilderRuntimeError,
+ throwBuilderValidationError,
+ type SemanticValidationIssue,
+} from "./errors";
+import { getNamedExpressionValidationIssues } from "./expression-validation";
import { runtimeGeneratedIdInput } from "./generated-id-input";
import {
collectExclusiveInstanceIds,
@@ -924,13 +931,17 @@ const pageMetaInputBase = z.object({
.optional(),
});
-export const getPageExpressionErrors = (input: PageFieldsPatchInput) => {
- const errors: string[] = [];
- errors.push(
- ...getNamedExpressionErrors("title", input.title, {
- hint: pageExpressionFieldHint,
- })
- );
+const collectPageExpressionValidationIssues = (input: PageFieldsPatchInput) => {
+ const issues: SemanticValidationIssue[] = [];
+ const add = (name: string, expression: string | undefined) => {
+ issues.push(
+ ...getNamedExpressionValidationIssues(name, expression, {
+ hint: pageExpressionFieldHint,
+ example: 'pageTitle ?? "Pricing"',
+ })
+ );
+ };
+ add("title", input.title);
if (input.meta !== undefined) {
for (const name of pageMetaExpressionFields) {
const expression = input.meta[name];
@@ -940,27 +951,35 @@ export const getPageExpressionErrors = (input: PageFieldsPatchInput) => {
if (expression === "" && emptyStringRemovesMetaFields.has(name)) {
continue;
}
- errors.push(
- ...getNamedExpressionErrors(`meta.${name}`, expression, {
- hint: pageExpressionFieldHint,
- })
- );
+ add(`meta.${name}`, expression);
}
for (const [index, customMeta] of (input.meta.custom ?? []).entries()) {
- errors.push(
- ...getNamedExpressionErrors(
- `meta.custom.${index}.content`,
- customMeta.content,
- {
- hint: pageExpressionFieldHint,
- }
- )
- );
+ add(`meta.custom.${index}.content`, customMeta.content);
}
}
- return errors;
+ return issues;
};
+export const getPageExpressionErrors = (input: PageFieldsPatchInput) =>
+ formatValidationIssueMessages(collectPageExpressionValidationIssues(input))
+ .split("\n")
+ .filter(Boolean);
+
+const getPagePathValidationIssues = (
+ path: string | undefined,
+ pathPrefix: readonly string[] = []
+) =>
+ getPagePathPatternErrors(path).map(
+ (detail): SemanticValidationIssue => ({
+ code: "invalid_page_path",
+ path: [...pathPrefix, "path"],
+ message: "Invalid page path pattern",
+ constraint: "valid_page_path_pattern",
+ example: "/pricing",
+ detail,
+ })
+ );
+
const getPagePathPatternErrors = (path: string | undefined) => {
if (path === undefined || path === "") {
return [];
@@ -989,13 +1008,17 @@ export const pageCustomMetadataSettingsInput = z.object({
.optional(),
});
-const emptyLanguageInput = z.string().refine((value) => value === "");
-const pageLanguageInput = z
- .string()
- .refine(
- (value) => bcp47.parse(value).language !== null,
- "The language is invalid"
- );
+const emptyLanguageInput = z.literal("");
+const pageLanguageInput = z.string().refine(
+ (value) => bcp47.parse(value).language !== null,
+ getZodValidationIssueOptions({
+ code: "invalid_page_language",
+ path: [],
+ message: "The language is invalid",
+ constraint: "bcp_47_language_tag",
+ example: "en-US",
+ })
+);
export const pageSearchSettingsInput = z.object({
title: pageTitle,
@@ -1009,12 +1032,16 @@ export const pageTemplateSettingsInput = z.object({
title: pageTitle,
});
-const pageStatusCodeInput = z
- .number()
- .refine(
- (value) => /^[2345]\d\d$/.test(String(value)),
- "Status code expects 2xx, 3xx, 4xx or 5xx"
- );
+const pageStatusCodeInput = z.number().refine(
+ (value) => /^[2345]\d\d$/.test(String(value)),
+ getZodValidationIssueOptions({
+ code: "invalid_page_status",
+ path: [],
+ message: "Status code expects 2xx, 3xx, 4xx or 5xx",
+ constraint: "http_status:200-599",
+ example: 200,
+ })
+);
export const pageGeneralSettingsInput = z.object({
name: pageName,
@@ -1708,15 +1735,19 @@ export const createPage = (
const normalizedInput = normalizePageFieldsExpressionInputs(input);
const parentFolderId = input.parentFolderId ?? pages.rootFolderId;
const parentFolder = getFolderOrThrow(pages, parentFolderId);
- const expressionErrors = getPageExpressionErrors(normalizedInput);
- if (expressionErrors.length > 0) {
- return throwBuilderRuntimeError("BAD_REQUEST", expressionErrors.join("\n"));
+ const expressionIssues =
+ collectPageExpressionValidationIssues(normalizedInput);
+ if (expressionIssues.length > 0) {
+ return throwBuilderValidationError(
+ formatValidationIssueMessages(expressionIssues),
+ expressionIssues
+ );
}
- const pathPatternErrors = getPagePathPatternErrors(input.path);
- if (pathPatternErrors.length > 0) {
- return throwBuilderRuntimeError(
- "BAD_REQUEST",
- pathPatternErrors.join("\n")
+ const pathIssues = getPagePathValidationIssues(input.path);
+ if (pathIssues.length > 0) {
+ return throwBuilderValidationError(
+ pathIssues.map((issue) => issue.detail).join("\n"),
+ pathIssues
);
}
const pageId = context.createId();
@@ -1771,15 +1802,21 @@ export const updatePage = (
return throwBuilderRuntimeError("NOT_FOUND", "Page not found");
}
const normalizedValues = normalizePageFieldsExpressionInputs(input.values);
- const expressionErrors = getPageExpressionErrors(normalizedValues);
- if (expressionErrors.length > 0) {
- return throwBuilderRuntimeError("BAD_REQUEST", expressionErrors.join("\n"));
+ const expressionIssues =
+ collectPageExpressionValidationIssues(normalizedValues);
+ if (expressionIssues.length > 0) {
+ return throwBuilderValidationError(
+ formatValidationIssueMessages(expressionIssues),
+ prefixValidationIssuePaths(expressionIssues, ["values"])
+ );
}
- const pathPatternErrors = getPagePathPatternErrors(normalizedValues.path);
- if (pathPatternErrors.length > 0) {
- return throwBuilderRuntimeError(
- "BAD_REQUEST",
- pathPatternErrors.join("\n")
+ const pathIssues = getPagePathValidationIssues(normalizedValues.path, [
+ "values",
+ ]);
+ if (pathIssues.length > 0) {
+ return throwBuilderValidationError(
+ pathIssues.map((issue) => issue.detail).join("\n"),
+ pathIssues
);
}
if (
diff --git a/packages/project-build/src/runtime/project-settings.ts b/packages/project-build/src/runtime/project-settings.ts
index 4f6dc6bff8..83f21becb7 100644
--- a/packages/project-build/src/runtime/project-settings.ts
+++ b/packages/project-build/src/runtime/project-settings.ts
@@ -16,7 +16,11 @@ import {
import type { BuilderState } from "../state/builder-state";
import { hasReachedBreakpointLimit, isBaseBreakpoint } from "./breakpoints";
import type { BuilderRuntimeContext } from "./context";
-import { throwBuilderRuntimeError } from "./errors";
+import {
+ getZodValidationIssueOptions,
+ throwBuilderRuntimeError,
+ throwBuilderValidationError,
+} from "./errors";
import { runtimeGeneratedIdInput } from "./generated-id-input";
import { createRuntimeMutation } from "./mutation";
import { getRequiredPages } from "./pages";
@@ -83,7 +87,13 @@ export const projectSettingsUpdateInput = z
({ meta, compiler }) =>
(meta !== undefined && Object.keys(meta).length > 0) ||
(compiler !== undefined && Object.keys(compiler).length > 0),
- { message: "Provide at least one project setting to update." }
+ getZodValidationIssueOptions({
+ code: "empty_project_settings_update",
+ path: [],
+ message: "Provide at least one project setting to update.",
+ constraint: "at_least_one_of:meta,compiler",
+ example: { meta: { siteName: "Acme" } },
+ })
)
.describe(
"Update at least one supported project meta or compiler setting. Null removes a setting."
@@ -182,13 +192,30 @@ const validateProjectMetaUpdate = (
if (typeof values.contactEmail === "string") {
const contactEmailError = validateContactEmail(values.contactEmail);
if (contactEmailError !== undefined) {
- return throwBuilderRuntimeError("BAD_REQUEST", contactEmailError);
+ return throwBuilderValidationError(contactEmailError, [
+ {
+ code: "invalid_contact_email",
+ path: ["meta", "contactEmail"],
+ message: contactEmailError,
+ constraint: "comma_separated_email_addresses",
+ example: "[email protected]",
+ },
+ ]);
}
}
if (typeof values.auth === "string") {
const authError = validateProjectAuth(values.auth);
if (authError !== undefined) {
- return throwBuilderRuntimeError("BAD_REQUEST", authError);
+ return throwBuilderValidationError(authError, [
+ {
+ code: "invalid_project_auth",
+ path: ["meta", "auth"],
+ message: "Invalid project authentication configuration",
+ constraint: "valid_webstudio_auth_json",
+ example: '{"version":1,"routes":{}}',
+ detail: authError,
+ },
+ ]);
}
}
};
diff --git a/packages/project-build/src/runtime/props.ts b/packages/project-build/src/runtime/props.ts
index 4f6b739d37..af35052563 100644
--- a/packages/project-build/src/runtime/props.ts
+++ b/packages/project-build/src/runtime/props.ts
@@ -7,7 +7,7 @@ import {
} from "@webstudio-is/sdk";
import { validateJsonLd } from "@webstudio-is/sdk/runtime";
import type { BuilderState } from "../state/builder-state";
-import { throwBuilderRuntimeError } from "./errors";
+import { addZodValidationIssue, throwBuilderRuntimeError } from "./errors";
import { replaceTextValue } from "./text-replacement";
import { getExpressionErrors } from "./expression-validation";
import { runtimeGeneratedIdInput } from "./generated-id-input";
@@ -113,10 +113,13 @@ const addExpressionIssues = (
path: (string | number)[] = []
) => {
for (const message of errors) {
- context.addIssue({
- code: z.ZodIssueCode.custom,
- message,
- path,
+ addZodValidationIssue(context, {
+ code: "invalid_expression",
+ path: path.map(String),
+ message: "Invalid Webstudio expression",
+ constraint: "valid_webstudio_expression",
+ example: "item.title",
+ detail: message,
});
}
};
diff --git a/packages/project-build/src/runtime/registry.test.ts b/packages/project-build/src/runtime/registry.test.ts
index b77acedddf..774b7a6c13 100644
--- a/packages/project-build/src/runtime/registry.test.ts
+++ b/packages/project-build/src/runtime/registry.test.ts
@@ -29,6 +29,7 @@ import { listDataVariables, listResources } from "./data";
import { listFonts } from "./fonts";
import { bindProps, deleteProps, updateProps } from "./props";
import type { BuilderState } from "../state/builder-state";
+import type { SemanticValidationIssue } from "./errors";
import {
context,
expectRuntimeValidationError,
@@ -64,6 +65,78 @@ const mutationOperationIds = runtimeOperationContracts
.filter((contract) => contract.kind === "mutation")
.map((contract) => contract.id);
+test.each([
+ {
+ family: "page",
+ operationId: "pages.create",
+ input: { name: false, path: "/" },
+ path: ["name"],
+ constraint: "type:string",
+ },
+ {
+ family: "instance",
+ operationId: "instances.move",
+ input: {
+ moves: [
+ { instanceId: "item", parentInstanceId: "parent", insertIndex: -1 },
+ ],
+ },
+ path: ["moves", "0", "insertIndex"],
+ constraint: "number:minimum:0",
+ },
+ {
+ family: "prop",
+ operationId: "instances.updateProps",
+ input: { updates: "not-an-array" },
+ path: ["updates"],
+ constraint: "type:array",
+ },
+ {
+ family: "style",
+ operationId: "styles.updateDeclarations",
+ input: { updates: [{ instanceId: "item", property: false, value: "red" }] },
+ path: ["updates", "0", "property"],
+ constraint: "type:string",
+ },
+ {
+ family: "resource",
+ operationId: "resources.create",
+ input: {
+ resource: { name: "Posts", method: "get", url: "/posts", headers: {} },
+ },
+ path: ["resource", "headers"],
+ constraint: "type:array",
+ },
+ {
+ family: "expression",
+ operationId: "instances.updateProps",
+ input: {
+ updates: [
+ {
+ instanceId: "item",
+ name: "title",
+ type: "expression",
+ value: "invalid {",
+ },
+ ],
+ },
+ path: ["updates", "0", "value"],
+ constraint: "valid_webstudio_expression",
+ },
+ {
+ family: "project settings",
+ operationId: "projectSettings.update",
+ input: { meta: { siteName: false } },
+ path: ["meta", "siteName"],
+ constraint: "type:string",
+ },
+])(
+ "returns an actionable $family input issue",
+ ({ operationId, input, path, constraint }) => {
+ expectRuntimeValidationError(operationId, input, { path, constraint });
+ }
+);
+
test("keeps generated runtime contracts in sync with the registry", () => {
expect(runtimeOperationContracts).toEqual(
builderRuntimeOperations.map(
@@ -1079,34 +1152,34 @@ describe("builder runtime read families", () => {
});
test("validates resource URL mutations through the public runtime operation", () => {
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "resources.create",
- state,
- input: {
- scopeInstanceId: "heading",
- resource: {
- name: "Users",
- method: "get",
- url: `"not-a-url"`,
- headers: [],
- },
+ expectRuntimeValidationError(
+ "resources.create",
+ {
+ scopeInstanceId: "heading",
+ resource: {
+ name: "Users",
+ method: "get",
+ url: `"not-a-url"`,
+ headers: [],
},
- context,
- })
- ).toThrow("url: URL is invalid");
+ },
+ {
+ path: ["resource", "url"],
+ constraint: "absolute_or_root_relative_url",
+ }
+ );
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "resources.update",
- state,
- input: {
- resourceId: "resource",
- values: { url: `""` },
- },
- context,
- })
- ).toThrow("url: URL is required");
+ expectRuntimeValidationError(
+ "resources.update",
+ {
+ resourceId: "resource",
+ values: { url: `""` },
+ },
+ {
+ path: ["values", "url"],
+ constraint: "absolute_or_root_relative_url",
+ }
+ );
const fixedUrlResult = executeBuilderRuntimeOperation({
id: "resources.create",
@@ -1295,38 +1368,38 @@ describe("builder runtime read families", () => {
});
test("validates project settings and redirects through public operations", () => {
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "projectSettings.update",
- state,
- input: {
- meta: { contactEmail: "not-an-email" },
- },
- context,
- })
- ).toThrow("Contact email is invalid.");
+ expectRuntimeValidationError(
+ "projectSettings.update",
+ { meta: { contactEmail: "not-an-email" } },
+ {
+ code: "invalid_contact_email",
+ path: ["meta", "contactEmail"],
+ constraint: "comma_separated_email_addresses",
+ }
+ );
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "projectSettings.update",
- state,
- input: {
- meta: {
- auth: JSON.stringify({
- version: 1,
- routes: {
- private: {
- method: "basic",
- login: "admin",
- password: "secret",
- },
+ expectRuntimeValidationError(
+ "projectSettings.update",
+ {
+ meta: {
+ auth: JSON.stringify({
+ version: 1,
+ routes: {
+ private: {
+ method: "basic",
+ login: "admin",
+ password: "secret",
},
- }),
- },
+ },
+ }),
},
- context,
- })
- ).toThrow('routes."private": Route must start with "/"');
+ },
+ {
+ code: "invalid_project_auth",
+ path: ["meta", "auth"],
+ constraint: "valid_webstudio_auth_json",
+ }
+ );
expect(() =>
executeBuilderRuntimeOperation({
@@ -1461,9 +1534,11 @@ describe("builder runtime registry", () => {
toInputJsonSchemaObject(copyPageSchema?.properties?.sourceData)
?.description
).toContain("use duplicate-page");
- expect(() =>
- copyPageOperation.execute({ state, input: { pageId: "home" }, context })
- ).toThrow("sourceData");
+ expectRuntimeValidationError(
+ "pages.copy",
+ { pageId: "home" },
+ { path: ["sourceData"] }
+ );
const duplicateStyleSourceOperation = getBuilderRuntimeOperation(
"styleSources.duplicate"
@@ -1694,18 +1769,91 @@ describe("builder runtime registry", () => {
}
});
+ test("returns actionable issues for semantic input relationships", () => {
+ const cases: Array<[string, unknown, Partial<SemanticValidationIssue>]> = [
+ [
+ "projectSettings.update",
+ {},
+ {
+ code: "empty_project_settings_update",
+ path: [],
+ constraint: "at_least_one_of:meta,compiler",
+ },
+ ],
+ [
+ "assets.update",
+ { assetId: "asset", values: {} },
+ {
+ code: "empty_asset_update",
+ path: ["values"],
+ constraint: "at_least_one_property",
+ },
+ ],
+ [
+ "assets.setImageDescriptions",
+ {
+ updates: [
+ { assetId: "asset", decorative: true },
+ { assetId: "asset", decorative: true },
+ ],
+ },
+ {
+ code: "duplicate_asset_update",
+ path: ["updates", "1", "assetId"],
+ constraint: "unique_by:assetId",
+ },
+ ],
+ [
+ "resources.create",
+ {
+ exposeAsDataSource: true,
+ resource: {
+ name: "Posts",
+ method: "get",
+ url: "https://api.example.com/posts",
+ headers: [],
+ },
+ },
+ {
+ code: "missing_resource_scope",
+ path: ["scopeInstanceId"],
+ constraint: "required_when:exposeAsDataSource=true",
+ },
+ ],
+ [
+ "instances.move",
+ {
+ moves: [
+ {
+ instanceId: "heading",
+ parentInstanceId: "body",
+ insertIndex: 0,
+ position: "end",
+ },
+ ],
+ },
+ {
+ code: "conflicting_move_position",
+ path: ["moves", "0", "position"],
+ constraint: "mutually_exclusive_with:insertIndex",
+ },
+ ],
+ ];
+
+ for (const [operationId, input, issue] of cases) {
+ expectRuntimeValidationError(operationId, input, issue);
+ }
+ });
+
test("validates internal runtime operation inputs without exposing them publicly", () => {
expect(
builderRuntimeOperations.map((operation) => operation.id)
).not.toContain("system.migrateLoadedData");
- expect(() =>
- executeBuilderRuntimeOperation({
- id: "system.migrateLoadedData",
- state,
- input: { unexpected: true },
- context,
- })
- ).toThrow(/unexpected/);
+ expectRuntimeValidationError(
+ "system.migrateLoadedData",
+ { unexpected: true },
+ { constraint: "recognized_keys_only" }
+ );
});
test("does not mutate caller state across representative public mutation surfaces", () => {
diff --git a/packages/project-build/src/runtime/registry.ts b/packages/project-build/src/runtime/registry.ts
index 8511dff758..9dd70d82f2 100644
--- a/packages/project-build/src/runtime/registry.ts
+++ b/packages/project-build/src/runtime/registry.ts
@@ -26,6 +26,7 @@ import * as props from "./props";
import * as search from "./search";
import * as audit from "./audit";
import * as styles from "./styles";
+import { getZodValidationIssues, throwBuilderValidationError } from "./errors";
export type BuilderRuntimeOperation<
Id extends string = string,
@@ -78,9 +79,19 @@ type RuntimeOperationContractInput =
requiresConfirm?: boolean;
};
+const throwInvalidOperationInput = (
+ error: z.ZodError,
+ inputJsonSchema: InputJsonSchema
+): never =>
+ throwBuilderValidationError(
+ "Operation input is invalid.",
+ getZodValidationIssues(error, inputJsonSchema)
+ );
+
const parseOperationInput = <Schema extends z.ZodTypeAny>(
schema: Schema,
- input: unknown
+ input: unknown,
+ inputJsonSchema: InputJsonSchema
): z.infer<Schema> => {
const result = schema.safeParse(input ?? {});
if (result.success) {
@@ -102,9 +113,13 @@ const parseOperationInput = <Schema extends z.ZodTypeAny>(
confirm: _confirm,
...operationInput
} = input as Record<string, unknown>;
- return schema.parse(operationInput);
+ const operationResult = schema.safeParse(operationInput);
+ if (operationResult.success) {
+ return operationResult.data;
+ }
+ return throwInvalidOperationInput(operationResult.error, inputJsonSchema);
}
- throw result.error;
+ return throwInvalidOperationInput(result.error, inputJsonSchema);
};
const bindExpressionInput = (
@@ -141,14 +156,15 @@ const runtimeOperation = <
): BuilderRuntimeOperation<Id, z.input<Schema>, Result> => {
const writeNamespaces =
contract.kind === "mutation" ? contract.writeNamespaces : [];
+ const inputJsonSchema = getInputSchemaMetadata(inputSchema, {
+ isHiddenField: isHiddenPublicApiInputField,
+ }).inputJsonSchema;
return {
id,
...publicApi,
kind: contract.kind,
inputSchema,
- inputJsonSchema: getInputSchemaMetadata(inputSchema, {
- isHiddenField: isHiddenPublicApiInputField,
- }).inputJsonSchema,
+ inputJsonSchema,
outputSchema,
outputJsonSchema:
outputSchema === undefined
@@ -175,7 +191,7 @@ const runtimeOperation = <
execute: ({ state, input, context }) => {
const result = execute({
state,
- input: parseOperationInput(inputSchema, input),
+ input: parseOperationInput(inputSchema, input, inputJsonSchema),
context,
});
if (outputSchema === undefined) {
diff --git a/packages/project-build/src/runtime/runtime.test-fixtures.ts b/packages/project-build/src/runtime/runtime.test-fixtures.ts
index 3f1b2566ba..9fbf5e84f0 100644
--- a/packages/project-build/src/runtime/runtime.test-fixtures.ts
+++ b/packages/project-build/src/runtime/runtime.test-fixtures.ts
@@ -1,6 +1,7 @@
import { expect } from "vitest";
import type { BuilderRuntimeContext } from "./context";
import type { BuilderState } from "../state/builder-state";
+import type { SemanticValidationIssue } from "./errors";
import { executeBuilderRuntimeOperation } from "./registry";
export const context: BuilderRuntimeContext = {
@@ -9,7 +10,8 @@ export const context: BuilderRuntimeContext = {
export const expectRuntimeValidationError = (
operationId: string,
- input: unknown
+ input: unknown,
+ expectedIssue?: Partial<SemanticValidationIssue>
) => {
try {
executeBuilderRuntimeOperation({
@@ -19,7 +21,18 @@ export const expectRuntimeValidationError = (
context,
});
} catch (error) {
- expect(error).toMatchObject({ name: "ZodError" });
+ expect(error).toMatchObject({
+ name: "BuilderRuntimeError",
+ code: "INVALID_INPUT",
+ issues: expect.any(Array),
+ });
+ if (expectedIssue !== undefined) {
+ expect(
+ (error as { issues?: readonly SemanticValidationIssue[] }).issues
+ ).toEqual(
+ expect.arrayContaining([expect.objectContaining(expectedIssue)])
+ );
+ }
return;
}
throw new Error(`Expected ${operationId} to reject invalid input`);
diff --git a/packages/protocol/src/builder-api/errors.test.ts b/packages/protocol/src/builder-api/errors.test.ts
index 2329de68f0..cbc34c665e 100644
--- a/packages/protocol/src/builder-api/errors.test.ts
+++ b/packages/protocol/src/builder-api/errors.test.ts
@@ -7,6 +7,7 @@ test("recognizes public API remote error codes", () => {
"CONFLICT",
"FORBIDDEN",
"INTERNAL_SERVER_ERROR",
+ "INVALID_INPUT",
"NOT_FOUND",
"PROJECT_NOT_PUBLISHED",
"UNAUTHORIZED",
diff --git a/packages/protocol/src/builder-api/errors.ts b/packages/protocol/src/builder-api/errors.ts
index dfcc1ffa0e..93d6ce1736 100644
--- a/packages/protocol/src/builder-api/errors.ts
+++ b/packages/protocol/src/builder-api/errors.ts
@@ -3,6 +3,7 @@ const publicApiRemoteErrorCodes = [
"CONFLICT",
"FORBIDDEN",
"INTERNAL_SERVER_ERROR",
+ "INVALID_INPUT",
"NOT_FOUND",
"PROJECT_NOT_PUBLISHED",
"UNAUTHORIZED",
diff --git a/packages/trpc-interface/src/context/router.server.test.ts b/packages/trpc-interface/src/context/router.server.test.ts
index e9e3cc21b4..d16b36aa33 100644
--- a/packages/trpc-interface/src/context/router.server.test.ts
+++ b/packages/trpc-interface/src/context/router.server.test.ts
@@ -1,3 +1,4 @@
+import { TRPCError } from "@trpc/server";
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { expect, test } from "vitest";
import type { AppContext } from "./context.server";
@@ -40,3 +41,41 @@ test("includes webstudio error codes in formatted tRPC errors", async () => {
},
});
});
+
+test("includes structured validation issues in formatted tRPC errors", async () => {
+ const issue = {
+ code: "invalid_type",
+ path: ["name"],
+ message: "Expected string",
+ constraint: "type:string",
+ };
+ const appRouter = router({
+ fail: procedure.query(() => {
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ cause: Object.assign(new Error("Invalid input"), {
+ webstudioCode: "INVALID_INPUT",
+ issues: [issue],
+ }),
+ });
+ }),
+ });
+
+ const response = await fetchRequestHandler({
+ endpoint: "/trpc",
+ req: new Request("http://localhost/trpc/fail"),
+ router: appRouter,
+ createContext,
+ });
+
+ expect(response.status).toBe(400);
+ await expect(response.json()).resolves.toMatchObject({
+ error: {
+ data: {
+ code: "BAD_REQUEST",
+ webstudioCode: "INVALID_INPUT",
+ issues: [issue],
+ },
+ },
+ });
+});
diff --git a/packages/trpc-interface/src/context/router.server.ts b/packages/trpc-interface/src/context/router.server.ts
index 3253e9317d..37774ce58c 100644
--- a/packages/trpc-interface/src/context/router.server.ts
+++ b/packages/trpc-interface/src/context/router.server.ts
@@ -13,6 +13,14 @@ const getWebstudioErrorCode = (cause: unknown) => {
return typeof code === "string" ? code : undefined;
};
+const getValidationIssues = (cause: unknown) => {
+ if (typeof cause !== "object" || cause === null) {
+ return;
+ }
+ const issues = (cause as { issues?: unknown }).issues;
+ return Array.isArray(issues) ? issues : undefined;
+};
+
export const {
router,
procedure,
@@ -31,8 +39,13 @@ export const {
})
: undefined);
const webstudioCode = getWebstudioErrorCode(error.cause);
+ const issues = getValidationIssues(error.cause);
- if (payload === undefined && webstudioCode === undefined) {
+ if (
+ payload === undefined &&
+ webstudioCode === undefined &&
+ issues === undefined
+ ) {
return shape;
}
@@ -42,6 +55,7 @@ export const {
...shape.data,
...(payload === undefined ? {} : { apiCompatibility: payload }),
...(webstudioCode === undefined ? {} : { webstudioCode }),
+ ...(issues === undefined ? {} : { issues }),
},
};
},