@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/index.js

@@ -1,8 +1,22 @@
-import { bindTools, getAllowedModes, isToolActive, resolveToolHandler, toolResponseErr, toolResponseOk, zodToJsonSchema } from "./modules/mcp/helpers.js";
-import { tools_exports } from "./modules/mcp/tools/index.js";
+import { buildAgentGuide } from "./modules/mcp/helpers/agentPrompt.js";
+import { operation } from "./modules/mcp/tools/operations/index.js";
+import { apply, applyShape } from "./modules/mcp/tools/apply/index.js";
+import { read, readShape } from "./modules/mcp/tools/read.js";
+import { search, searchShape } from "./modules/mcp/tools/search.js";
+import { validate, validateShape } from "./modules/mcp/tools/validate.js";
+import { tools } from "./modules/mcp/tools/index.js";
+import { bindTools, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema } from "./modules/ai/toolkit.js";
 import { createMcpServer } from "./modules/mcp/server.js";
-import AIEngine from "./modules/ai/AIEngine.js";
-import { handleMcp, readMcpBody } from "./modules/mcp/handler.js";
-import { createSSRServer } from "./core/createServer.js";
+import { handleMcp, readMcpBody, serveMcp } from "./modules/mcp/handler.js";
+import { createHttpPreviewClient } from "./modules/mcp/previewClient.js";
+import { PREVIEW_TOKEN_PARAM } from "./modules/mcp/constants.js";
+import { createHttpScreenshotClient } from "./modules/mcp/screenshotClient.js";
+import { createMemoryDraftStore, createPreview } from "./modules/ssr/preview.js";
+import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
+import { createMCPServer } from "./core/server/mcpServer.js";
+import { resolveServices } from "./core/services/resolve.js";
+import { createSSRServer } from "./core/server/ssrServer.js";
+import { createServer } from "./core/createServer.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
-export { AIEngine, bindTools, createJsonAdapters, createMcpServer, createSSRServer, getAllowedModes, handleMcp, isToolActive, readMcpBody, resolveToolHandler, toolResponseErr, toolResponseOk, tools_exports as tools, zodToJsonSchema };
+import AIEngine from "./modules/ai/AIEngine.js";
+export { AIEngine, PREVIEW_TOKEN_PARAM, apply, applyShape, bindTools, buildAgentGuide, buildHealthPayload, createHttpPreviewClient, createHttpScreenshotClient, createJsonAdapters, createMCPServer, createMcpServer, createMemoryDraftStore, createPreview, createSSRServer, createServer, getAllowedModes, handleMcp, isCallToolResult, isToolActive, operation, read, readMcpBody, readShape, registerHealthCheck, resolveServices, resolveToolHandler, search, searchShape, serveMcp, toolResponseErr, toolResponseFromResult, toolResponseOk, tools, validate, validateShape, zodToJsonSchema };

package/dist/modules/ai/AIEngine.js

@@ -1,4 +1,4 @@
-import { toolResponseErr } from "../mcp/helpers.js";
+import { firstText, toolResponseErr } from "./toolkit.js";
 //#region src/modules/ai/AIEngine.ts
 var AIEngine = class {
 	mode;
@@ -44,12 +44,12 @@ var AIEngine = class {
 		let resultParsed;
 		if (result.data !== void 0) resultParsed = result.data;
 		else try {
-			resultParsed = JSON.parse(result.content[0]?.text ?? "");
+			resultParsed = JSON.parse(firstText(result.content) ?? "");
 		} catch {}
 		if (result.isError) this.callbacks.onToolError?.({
 			name,
 			args,
-			result: resultParsed ?? { error: result.content[0]?.text ?? "Tool failed" }
+			result: resultParsed ?? { error: firstText(result.content) ?? "Tool failed" }
 		});
 		else this.callbacks.onToolSuccess?.({
 			name,
@@ -96,7 +96,7 @@ var AIEngine = class {
 		if (outputError) this.callbacks.onLog?.("info", `tool output schema drift: ${name} — ${outputError}`);
 		const tool = this.toolsAvailables.get(name);
 		if (!result.isError && tool?.mcpDefinition.outputSchema && result.data !== void 0 && result.data !== null) result.structuredContent = typeof result.data === "object" && !Array.isArray(result.data) ? result.data : { data: result.data };
-		if (result.isError) this.callbacks.onLog?.("error", `tool failed: ${name} error=${result.content[0]?.text ?? "unknown"}`);
+		if (result.isError) this.callbacks.onLog?.("error", `tool failed: ${name} error=${firstText(result.content) ?? "unknown"}`);
 		await this.after(name, args, result);
 		return result;
 	};

package/dist/modules/ai/toolkit.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+//#region src/modules/ai/toolkit.ts
+/** Convert a Zod schema to the JSON Schema an AI provider (Anthropic / OpenAI) expects in a tool definition.
+*  Delegates to Zod v4's built-in converter — one implementation, so descriptions, literal discriminators,
+*  enums, nested objects and recursive (z.lazy) shapes all survive and the provider sees the same contract an
+*  MCP client does. `io: 'input'` describes what the agent must SEND; `unrepresentable: 'any'` degrades an
+*  exotic type to an empty schema instead of throwing, so one unusual tool never breaks the whole tool list. */
+var zodToJsonSchema = (schema) => {
+	const json = z.toJSONSchema(schema, {
+		target: "draft-7",
+		io: "input",
+		unrepresentable: "any"
+	});
+	delete json.$schema;
+	return json;
+};
+var firstText = (content) => content.find((block) => block.type === "text")?.text;
+var getAllowedModes = (operationType) => {
+	return operationType === "write" ? ["build"] : ["plan", "build"];
+};
+var toolResponseOk = (data, agentMessage) => {
+	return {
+		content: [{
+			type: "text",
+			text: agentMessage ?? JSON.stringify(data ?? null, null, 2)
+		}],
+		data
+	};
+};
+var toolResponseErr = (error) => ({
+	content: [{
+		type: "text",
+		text: error instanceof Error ? error.message : error
+	}],
+	isError: true
+});
+var isCallToolResult = (result) => typeof result === "object" && result !== null && Array.isArray(result.content);
+var toolResponseFromResult = (result) => {
+	const content = [];
+	for (const block of result.content) if (block.type === "text") content.push({
+		type: "text",
+		text: block.text
+	});
+	else if (block.type === "image") content.push({
+		type: "image",
+		data: block.data,
+		mimeType: block.mimeType
+	});
+	return {
+		content,
+		isError: result.isError ? true : void 0
+	};
+};
+var isToolActive = (tool) => Boolean(tool.handler);
+var resolveToolHandler = (tool) => tool.handler;
+var bindTools = (tools) => tools.filter(isToolActive);
+//#endregion
+export { bindTools, firstText, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema };

package/dist/modules/mcp/catalogs/builtinCallbacks.js

@@ -0,0 +1,204 @@
+import { reconcileParams } from "./paramSpec.js";
+//#region src/modules/mcp/catalogs/builtinCallbacks.ts
+var BUILTIN_GLOBAL_CALLBACKS = {
+	addNotification: {
+		source: "space",
+		title: "Add Notification",
+		strictParams: true,
+		params: {
+			content: {
+				type: "textarea",
+				description: "The notification text shown to the user — this is the message body. There is no separate title/message/type param.",
+				default: "Content"
+			},
+			placement: {
+				type: "select",
+				description: "Where the toast appears on screen.",
+				default: "top-right",
+				options: [
+					"top-right",
+					"top-center",
+					"top-left",
+					"bottom-right",
+					"bottom-center",
+					"bottom-left"
+				]
+			},
+			appeareance: {
+				type: "select",
+				description: "Visual style of the notification. NOTE: the key is spelled \"appeareance\".",
+				default: "success",
+				options: [
+					"success",
+					"danger",
+					"warning",
+					"info"
+				]
+			},
+			autoDismiss: {
+				type: "boolean",
+				description: "Whether the notification dismisses itself after a timeout.",
+				default: true
+			},
+			autoDismissTimeout: {
+				type: "number",
+				description: "Milliseconds before auto-dismiss. Only applies when autoDismiss is true.",
+				default: 5e3,
+				when: (params) => params.autoDismiss === true
+			}
+		}
+	},
+	setState: {
+		source: "state",
+		title: "Set State",
+		strictParams: true,
+		params: {
+			key: {
+				type: "text",
+				description: "The state key/path to set.",
+				default: ""
+			},
+			type: {
+				type: "select",
+				description: "The value type.",
+				options: [
+					"boolean",
+					"number",
+					"text"
+				]
+			},
+			value: {
+				type: "scalar",
+				description: "The value to store — its type follows the `type` param (a real boolean/number, or text).",
+				when: (params) => Boolean(params.type)
+			}
+		}
+	},
+	clearState: {
+		source: "state",
+		title: "Clear State",
+		strictParams: true,
+		params: {}
+	},
+	navigate: {
+		source: "navigation",
+		title: "Navigate",
+		strictParams: true,
+		params: {
+			urlType: {
+				type: "select",
+				description: "Target kind: a space page, an internal space path, or an external URL.",
+				options: [
+					"page",
+					"internal",
+					"external"
+				]
+			},
+			url: {
+				type: "text",
+				description: "Destination — a page id when urlType is \"page\", otherwise a URL/path.",
+				when: (params) => Boolean(params.urlType)
+			}
+		}
+	},
+	authLogin: {
+		source: "auth",
+		title: "Auth Login",
+		strictParams: true,
+		params: {}
+	},
+	authLogout: {
+		source: "auth",
+		title: "Auth Logout",
+		strictParams: true,
+		params: {}
+	},
+	authRefreshDetails: {
+		source: "auth",
+		title: "Auth Refresh Details",
+		strictParams: true,
+		params: {}
+	},
+	addCollectionRecord: {
+		source: "collection",
+		title: "Add Collection Record",
+		strictParams: false,
+		params: {
+			collectionId: {
+				type: "select",
+				description: "The collection to add the record to."
+			},
+			recordStatus: {
+				type: "select",
+				description: "Status of the new record.",
+				default: "draft",
+				options: [
+					"published",
+					"draft",
+					"archived",
+					"deleted",
+					"created"
+				]
+			}
+		}
+	},
+	updateCollectionRecord: {
+		source: "collection",
+		title: "Update Collection Record",
+		strictParams: false,
+		params: {
+			collectionId: {
+				type: "select",
+				description: "The collection the record belongs to."
+			},
+			recordId: {
+				type: "select",
+				description: "The record to update."
+			},
+			recordStatus: {
+				type: "select",
+				description: "New status for the record.",
+				default: "draft",
+				options: [
+					"published",
+					"draft",
+					"archived",
+					"deleted",
+					"created"
+				]
+			}
+		}
+	},
+	removeCollectionRecord: {
+		source: "collection",
+		title: "Remove Collection Record",
+		strictParams: false,
+		params: {
+			collectionId: {
+				type: "select",
+				description: "The collection the record belongs to."
+			},
+			recordId: {
+				type: "select",
+				description: "The record to remove."
+			}
+		}
+	}
+};
+/** The built-in globalCallback for an action, or undefined when the action is not a known built-in (a plugin
+*  callback whose source/schema is not knowable here). */
+var getGlobalCallback = (action) => Object.hasOwn(BUILTIN_GLOBAL_CALLBACKS, action) ? BUILTIN_GLOBAL_CALLBACKS[action] : void 0;
+/** Resolve a `globalCallback` action against the built-in catalog: returns the module id it is registered under
+*  (`source`) and the params reconciled to the callback's schema — unknown keys dropped for a closed callback, then
+*  missing defaults filled. An action the catalog does not know (e.g. a plugin callback) yields no source and
+*  unchanged params, so the caller keeps its own behavior for it. */
+var applyBuiltinCallback = (action, params) => {
+	if (!(action in BUILTIN_GLOBAL_CALLBACKS)) return { params };
+	const builtin = BUILTIN_GLOBAL_CALLBACKS[action];
+	return {
+		source: builtin.source,
+		params: reconcileParams(params, builtin.params, builtin.strictParams)
+	};
+};
+//#endregion
+export { BUILTIN_GLOBAL_CALLBACKS, applyBuiltinCallback, getGlobalCallback };

package/dist/modules/mcp/catalogs/builtinComponents.js

@@ -0,0 +1,170 @@
+//#region src/modules/mcp/catalogs/builtinComponents.ts
+var BUILTIN_COMPONENTS = {
+	container: {
+		label: "Container",
+		category: "structure",
+		description: "Generic layout box (a div). The primary building block for structure: groups and positions child elements with flex/grid. Reach for it whenever you need to wrap or arrange other elements."
+	},
+	list: {
+		label: "List",
+		category: "structure",
+		description: "Repeats a template (its listItem/link child) once per entry of a data array — the way to render a dynamic collection. Bind its items to a data source (e.g. an apiContainer/collectionContainer response)."
+	},
+	listItem: {
+		label: "List Item",
+		category: "structure",
+		description: "The repeated template rendered once per row inside a list; its fields bind to each array entry."
+	},
+	dialogContainer: {
+		label: "Dialog Container",
+		category: "structure",
+		description: "A native <dialog> container shown or hidden through interactions (e.g. an onClick open/close)."
+	},
+	modalContainer: {
+		label: "Modal Container",
+		category: "structure",
+		description: "A modal overlay container opened and closed through interactions; use for dialogs over the page."
+	},
+	tabContainer: {
+		label: "Tab Container",
+		category: "structure",
+		description: "A tabbed container that switches between panels; composed of header/body/item parts."
+	},
+	tabContainerHeader: {
+		label: "Tab Container Header",
+		category: "structure",
+		description: "The row of tab triggers inside a tabContainer."
+	},
+	tabContainerBody: {
+		label: "Tab Container Body",
+		category: "structure",
+		description: "The panel area inside a tabContainer that shows the active tab item."
+	},
+	tabContainerItem: {
+		label: "Tab Container Item",
+		category: "structure",
+		description: "One selectable tab (trigger + panel) inside a tabContainer."
+	},
+	apiContainer: {
+		label: "Api Container",
+		category: "provider",
+		description: "Fetches data from a backend HTTP API (its `query`/`method`/`credentials`) and exposes the response as a data source ITS DESCENDANTS bind to (source `apiContainer_<idRef>.data`; only elements inside it can consume it). This is how you get backend data into the frontend. Its `mockData` prop is builder-only sample data — the published runtime fetches the real `query`, so always set a real query for production."
+	},
+	collectionContainer: {
+		label: "Collection Container",
+		category: "provider",
+		description: "Exposes a Plitzi Collection (built-in CMS) as a data source for its descendants to bind to — the CMS-backed counterpart of apiContainer."
+	},
+	text: {
+		label: "Text",
+		category: "basic",
+		description: "Inline plain-text content. Use for short runs of copy; bind its content to data for dynamic text."
+	},
+	paragraph: {
+		label: "Paragraph",
+		category: "basic",
+		description: "A block of body text (a <p>). Use for longer prose passages."
+	},
+	heading: {
+		label: "Heading",
+		category: "basic",
+		description: "A section heading (<h1>–<h6>) for titles and document hierarchy."
+	},
+	button: {
+		label: "Button",
+		category: "basic",
+		description: "A clickable button. On its own it only renders; wire an interaction flow (trigger onClick → callbacks) to make it DO something."
+	},
+	link: {
+		label: "Link",
+		category: "basic",
+		description: "Navigation. Moves the user between pages of the site or to an external URL (its `mode`/`href` decide which). Use this to go page-to-page rather than a button + interaction."
+	},
+	markdown: {
+		label: "Markdown",
+		category: "basic",
+		description: "Renders a Markdown source string as formatted HTML."
+	},
+	dropdown: {
+		label: "Dropdown",
+		category: "basic",
+		description: "A trigger that toggles an attached popup panel (dropdownPopup) — menus, selects, flyouts."
+	},
+	dropdownPopup: {
+		label: "Dropdown Popup",
+		category: "basic",
+		description: "The floating panel revealed by a dropdown."
+	},
+	form: {
+		label: "Form",
+		category: "form",
+		description: "A <form> that groups form controls and handles submission; wire its submit through an interaction flow."
+	},
+	formControl: {
+		label: "Form Control",
+		category: "form",
+		description: "A single labelled input (text/select/checkbox/… per its subType) inside a form; captures one field of user input."
+	},
+	image: {
+		label: "Image",
+		category: "media",
+		description: "Displays an image from a URL."
+	},
+	video: {
+		label: "Video",
+		category: "media",
+		description: "Embeds a video from a URL."
+	},
+	fontAwesome: {
+		label: "Font Awesome",
+		category: "media",
+		description: "Renders a Font Awesome icon by its icon name."
+	},
+	page: {
+		label: "Page",
+		category: "internal",
+		description: "The root of a routable screen. Managed through the page ops (upsertPage/deletePage), not added as a child element."
+	},
+	layoutContainer: {
+		label: "Layout Container",
+		category: "internal",
+		description: "A reusable layout shell (header/footer chrome) shared across pages."
+	},
+	notFound: {
+		label: "Not Found",
+		category: "internal",
+		description: "The 404 screen shown when no route matches."
+	},
+	loading: {
+		label: "Loading",
+		category: "internal",
+		description: "A loading placeholder shown while data or a suspense boundary resolves."
+	},
+	reference: {
+		label: "Reference",
+		category: "advanced",
+		description: "Reuses another element or template by id, rendering it in place."
+	},
+	custom: {
+		label: "Custom",
+		category: "advanced",
+		description: "A custom element slot whose behaviour is supplied by a host/plugin component."
+	},
+	blockHtml: {
+		label: "HTML Block",
+		category: "advanced",
+		description: "Renders an arbitrary raw HTML string as a block. Escape hatch when no structured element fits."
+	},
+	nodeHtml: {
+		label: "Html Node",
+		category: "advanced",
+		description: "A single raw HTML tag with custom attributes."
+	},
+	blockJsx: {
+		label: "Block JSX",
+		category: "advanced",
+		description: "A compiled JSX block for advanced authoring."
+	}
+};
+//#endregion
+export { BUILTIN_COMPONENTS };

package/dist/modules/mcp/catalogs/builtinElementCallbacks.js

@@ -0,0 +1,50 @@
+import { reconcileParams } from "./paramSpec.js";
+//#region src/modules/mcp/catalogs/builtinElementCallbacks.ts
+var BUILTIN_ELEMENT_CALLBACKS = { setState: {
+	title: "Update Element (set attribute / state)",
+	strictParams: true,
+	params: {
+		category: {
+			type: "select",
+			description: "What to change on the element: \"attribute\" sets one of its props (the common case — e.g. content, disabled); \"state\" sets element state (visibility or a style selector). REQUIRED — always set it.",
+			default: "attribute",
+			options: ["attribute", "state"],
+			required: true
+		},
+		key: {
+			type: "text",
+			description: "The field to set. When category=\"attribute\", an attribute/prop key of THIS element (e.g. \"content\", \"disabled\"). When category=\"state\", \"visibility\" or \"styleSelectors.<selector>\". REQUIRED.",
+			required: true
+		},
+		value: {
+			type: "scalar",
+			description: "The value to set — its type follows the target attribute: a real boolean (true/false) for a boolean attribute, a number for a numeric one, otherwise a string (the strings \"true\"/\"false\" also coerce). There is NO separate `type` param (that belongs to the global state setState, not this one). REQUIRED.",
+			when: (params) => Boolean(params.category),
+			required: true
+		},
+		revertOnFinish: {
+			type: "boolean",
+			description: "When true, this change is UNDONE automatically when the whole flow finishes. Use it for a TEMPORARY change (a \"loading…\" label, disabling a button while it works) instead of adding manual restore steps at the end of the flow.",
+			default: false
+		}
+	}
+} };
+/** The built-in element callback for an action, or undefined when the action is not a known built-in (an
+*  element-type-specific/plugin callback whose schema is not knowable here). */
+var getElementCallback = (action) => Object.hasOwn(BUILTIN_ELEMENT_CALLBACKS, action) ? BUILTIN_ELEMENT_CALLBACKS[action] : void 0;
+/** Reconcile a `callback` action against the element-callback catalog: unknown keys dropped for a closed callback,
+*  then missing defaults filled (category:"attribute", revertOnFinish:false). An unknown action yields unchanged
+*  params, so a plugin/element-specific callback keeps whatever the agent passed. */
+var applyElementCallback = (action, params) => {
+	const builtin = getElementCallback(action);
+	if (!builtin) return {
+		known: false,
+		params
+	};
+	return {
+		known: true,
+		params: reconcileParams(params, builtin.params, builtin.strictParams)
+	};
+};
+//#endregion
+export { BUILTIN_ELEMENT_CALLBACKS, applyElementCallback, getElementCallback };