@plitzi/sdk-server 0.32.4 → 0.32.6

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

@@ -0,0 +1,89 @@
+import { BUILTIN_COMPONENTS } from "./builtinComponents.js";
+import { cssProperties } from "./cssCatalog.js";
+//#region src/modules/mcp/catalogs/registry.ts
+var enrichType = (typeName, info, catalog) => {
+	const entry = catalog?.[typeName];
+	if (entry) {
+		info.label = entry.label ?? info.label;
+		if (entry.description !== void 0) info.description = entry.description;
+		if (entry.category !== void 0) info.category = entry.category;
+		info.source = entry.custom ? "plugin" : "builtin";
+		if (entry.defaultStyle && Object.keys(entry.defaultStyle).length > 0) info.defaultStyle = entry.defaultStyle;
+		for (const attr of entry.attributes ?? []) info.props[attr] ??= {
+			valueTypes: [],
+			examples: []
+		};
+		for (const slot of entry.styleSelectors ?? []) if (!info.slots.includes(slot)) info.slots.push(slot);
+		return;
+	}
+	const builtin = BUILTIN_COMPONENTS[typeName];
+	if (builtin) {
+		info.label = builtin.label;
+		info.description = builtin.description;
+		info.category = builtin.category;
+		info.source = "builtin";
+	}
+};
+var EXAMPLE_MAX_LENGTH = 80;
+var isCompactExample = (value) => {
+	if (typeof value === "string") return value.length <= EXAMPLE_MAX_LENGTH;
+	return typeof value === "number" || typeof value === "boolean";
+};
+var NOTE = "Element types and their props/slots are observed from the elements that already exist in this space — they are ground truth, never inferred. Each type also carries a `label`, `description` (what it is FOR) and `category`, plus a `source`: \"builtin\" (a Plitzi element), \"plugin\" (a custom element added via a plugin), or \"unknown\" (observed but undescribed — label only). Use the description to pick the right type (e.g. apiContainer fetches backend data, link navigates between pages). Props list the attribute keys seen on each type with example values. Slots are the styleSelectors keys seen on each type (target them via element.style.slots). `defaultStyle` (when present) is the intrinsic base CSS of the type BEFORE any class is attached — the real starting point, so account for it and never assume `display: block` (e.g. `text` is `display: inline`; wrap or override it explicitly if you need block/flex layout). CSS in definitions must use the kebab-case keys in cssProperties. Reference schema variables in props via {{name}} and style variables in CSS via var(--name).";
+var buildTypeRegistry = (schema, catalog) => {
+	const types = {};
+	for (const el of Object.values(schema.flat)) {
+		const typeName = el.definition.type;
+		const info = types[typeName] ??= {
+			count: 0,
+			source: "unknown",
+			subTypes: [],
+			slots: [],
+			props: {}
+		};
+		info.count += 1;
+		if (!info.label && typeof el.definition.label === "string" && el.definition.label !== "") info.label = el.definition.label;
+		const subType = el.attributes.subType;
+		if (typeof subType === "string" && !info.subTypes.includes(subType)) info.subTypes.push(subType);
+		for (const slot of Object.keys(el.definition.styleSelectors)) if (!info.slots.includes(slot)) info.slots.push(slot);
+		for (const [key, value] of Object.entries(el.attributes)) {
+			if (key === "subType") continue;
+			const prop = info.props[key] ??= {
+				valueTypes: [],
+				examples: []
+			};
+			const valueType = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+			if (!prop.valueTypes.includes(valueType)) prop.valueTypes.push(valueType);
+			if (prop.examples.length < 3 && isCompactExample(value) && value !== "" && !prop.examples.includes(value)) prop.examples.push(value);
+		}
+	}
+	for (const typeName of Object.keys(catalog ?? {})) types[typeName] ??= {
+		count: 0,
+		source: "unknown",
+		subTypes: [],
+		slots: [],
+		props: {}
+	};
+	for (const [typeName, info] of Object.entries(types)) {
+		enrichType(typeName, info, catalog);
+		info.subTypes.sort();
+		info.slots.sort();
+	}
+	return {
+		note: NOTE,
+		cssProperties,
+		styleVariableCategories: [
+			"color",
+			"spacing",
+			"shadow",
+			"custom"
+		],
+		templateSyntax: {
+			schemaVariable: "{{name}}",
+			styleVariable: "var(--name)"
+		},
+		types
+	};
+};
+//#endregion
+export { buildTypeRegistry };

package/dist/modules/mcp/constants.js

@@ -0,0 +1,4 @@
+//#region src/modules/mcp/constants.ts
+var PREVIEW_TOKEN_PARAM = "__pt";
+//#endregion
+export { PREVIEW_TOKEN_PARAM };

package/dist/modules/mcp/handler.js

@@ -1,5 +1,4 @@
 import { createMcpServer } from "./server.js";
-import AIEngine from "../ai/AIEngine.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp";
 //#region src/modules/mcp/handler.ts
 var readMcpBody = (req) => new Promise((resolve, reject) => {
@@ -16,38 +15,43 @@ var readMcpBody = (req) => new Promise((resolve, reject) => {
 	});
 	req.on("error", reject);
 });
-var handleMcp = async (req, res, config, server, transport, context) => {
-	if (!server) {
-		const ctx = context ?? {
-			userId: 0,
-			spaceId: 0,
-			environment: "main",
-			mode: "plan"
-		};
-		const engine = new AIEngine(ctx.mode, {}, ctx);
-		server = createMcpServer(config.adapters, engine, config.tools, config.prompts);
+var serveMcp = async (raw, res, server) => {
+	res.setHeader("Access-Control-Allow-Origin", "*");
+	res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+	res.setHeader("Access-Control-Allow-Headers", "*");
+	res.setHeader("Access-Control-Max-Age", "86400");
+	if (raw.method === "OPTIONS") {
+		res.writeHead(204);
+		res.end();
+		return;
 	}
-	if (!transport) transport = new StreamableHTTPServerTransport({
+	const transport = new StreamableHTTPServerTransport({
 		sessionIdGenerator: void 0,
 		enableJsonResponse: true
 	});
 	await server.connect(transport);
 	try {
-		if (req.method === "POST") {
-			let body;
-			if (req.body !== void 0) body = req.body;
-			else try {
-				body = await readMcpBody(req);
+		if (raw.method === "POST") {
+			let body = raw.body;
+			if (body === void 0) try {
+				body = await readMcpBody(raw);
 			} catch {
 				res.writeHead(400, { "Content-Type": "application/json" });
 				res.end(JSON.stringify({ error: "Invalid JSON body" }));
 				return;
 			}
-			await transport.handleRequest(req, res, body);
-		} else await transport.handleRequest(req, res);
+			await transport.handleRequest(raw, res, body);
+		} else await transport.handleRequest(raw, res);
 	} finally {
 		await transport.close();
 	}
 };
+var handleMcp = (raw, res, req, adapters, preview, screenshot, logger) => serveMcp(raw, res, createMcpServer({
+	adapters,
+	getSpaceId: () => adapters.getSpaceId?.(req) ?? Promise.resolve(void 0),
+	preview,
+	screenshot,
+	logger
+}));
 //#endregion
-export { handleMcp, readMcpBody };
+export { createMcpServer, handleMcp, readMcpBody, serveMcp };

package/dist/modules/mcp/helpers/agentPrompt.js

@@ -0,0 +1,104 @@
+import { BUILTIN_GLOBAL_CALLBACKS } from "../catalogs/builtinCallbacks.js";
+import { BUILTIN_ELEMENT_CALLBACKS } from "../catalogs/builtinElementCallbacks.js";
+import { BUILTIN_UTILITIES } from "../catalogs/builtinUtilities.js";
+//#region src/modules/mcp/helpers/agentPrompt.ts
+var EDITING_MODEL = [
+	"━━ PLITZI MCP — EDITING MODEL ━━",
+	"A Plitzi space is TWO schemas you edit together in one atomic plitzi_apply batch:",
+	"• Element schema — the tree of pages/elements (type, label, props, and which style classes each uses).",
+	"• Style schema — reusable definitions (CSS classes), design tokens (variables), theme.",
+	"To style an element: write a definition AND attach it via the element’s style.base in the same batch.",
+	"style.base is a LIST — an element can attach several classes (plus non-base slots); ALL of them apply together",
+	"(they cascade), so when a style looks wrong inspect EVERY attached class + its global/id styles, not just one.",
+	"Refs accept a semantic idRef ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) or the raw id; the",
+	"idRef is ALSO the runtime wiring key (a provider source is `<type>_<idRef>.<field>` — a dot is not allowed in the",
+	"idRef, an underscore is). CSS is kebab-case; style vars are var(--name), schema",
+	"vars are {{name}}. Use patchElement/patchDefinition to change SOME props/CSS; the upsert variants replace them all.",
+	"Reads are cheap by design — list to navigate, read one item for detail; never fetch a whole tree you do not need."
+].join("\n");
+var TOOLS = [
+	"━━ MCP TOOLS ━━",
+	"• plitzi_search — find refs by label/type/attribute (include:\"detail\" also returns each hit’s style + versions).",
+	"• plitzi_read — batch-read one or more resource URIs you already hold (from search or a write response).",
+	"• plitzi_validate — check a batch of operations without executing; returns teachable errors and warnings.",
+	"• plitzi_apply — persist a batch of operations. Pass dryRun to preview the full diff without writing, and",
+	"  expectedResourceVersions to guard against concurrent edits (apply and search hand back the versions you need).",
+	"• plitzi_preview / plitzi_screenshot — render an element/page already in the schema (HTML / image).",
+	"Discover → browse resources. Find a ref → plitzi_search. Fetch known URIs → plitzi_read. Do not confuse them."
+].join("\n");
+var RESOURCES = [
+	"━━ MCP RESOURCES (read) ━━",
+	"Read plitzi://primer/{env} FIRST — a cold-start bundle: guide + types + css-properties + page/definition/variable",
+	"summaries in one call. Then, on demand:",
+	"• plitzi://guide — full usage reference.",
+	"• plitzi://types — element types observed in this space (props, slots, subTypes, label/description/category).",
+	"• plitzi://css-properties — valid kebab-case CSS property keys.",
+	"• plitzi://schema/{env}/pages , /{ref} — page summaries, then one page as a skeleton tree.",
+	"• plitzi://folders/{env} — page folders (the sidebar tree).",
+	"• plitzi://definitions/{env} , plitzi://style-variables/{env} — style classes and design tokens.",
+	"• plitzi://interactions/{env} — interaction actions + built-in globalCallbacks with their source + param schema.",
+	"• plitzi://data-sources/{env} — data-source paths and binding targets (vocabulary for upsertBinding).",
+	"• plitzi://settings/{env} — space-level settings."
+].join("\n");
+var NAVIGATION = [
+	"━━ NAVIGATION & DYNAMIC PAGES ━━",
+	"To move between pages, PREFER the Link element over an interaction — it is a CONTAINER that wraps any children and",
+	"navigates on click. mode \"page\" links to another space page (href = the target page); mode \"internal\" takes a",
+	"path inside the space and resolves {{token}} templates in it (e.g. /posts/{{postId}}); mode \"external\" is a full",
+	"URL. Reach for the navigate globalCallback only when navigation must be one step inside a larger flow.",
+	"A page slug is RELATIVE — never start it with \"/\" (the runtime prepends it). Folder slugs PREPEND to the page",
+	"slug, so a page at slug \"post\" inside folders \"blog\" > \"2024\" resolves to /blog/2024/post.",
+	"A slug segment \":name\" (e.g. \"posts/:postId\") declares a ROUTE PARAM, react-router style. It is readable on that",
+	"page as {{name}} in props AND as the binding source navigation.routeParams.name — so a dynamic detail page is a",
+	"\"posts/:postId\" page whose apiContainer query binds navigation.routeParams.postId."
+].join("\n");
+var paramList = (params) => {
+	const names = Object.keys(params);
+	return names.length > 0 ? names.join(", ") : "(no params)";
+};
+var globalCallbackLines = () => Object.entries(BUILTIN_GLOBAL_CALLBACKS).map(([action, { source, params }]) => `  • ${action} → source "${source}"; params: ${paramList(params)}`);
+var elementCallbackLines = () => Object.entries(BUILTIN_ELEMENT_CALLBACKS).map(([action, { params }]) => `  • ${action}; params: ${paramList(params)}`);
+var utilityLines = () => Object.entries(BUILTIN_UTILITIES).map(([action, { params }]) => `  • ${action}; params: ${paramList(params)}`);
+var INTERACTIONS = () => [
+	"━━ INTERACTIONS ━━",
+	"A flow is a trigger (onClick, onPageLoad…) followed by ordered callbacks/utilities; each step has an enabled",
+	"flag. Write one with upsertInteractionFlow (first node MUST be a trigger); change one step with",
+	"patchInteractionNode; remove a step (nodeId) or a whole flow (flowId) with deleteInteraction.",
+	"Disable ≠ delete: to turn a step off without removing it use patchInteractionNode { enabled: false }.",
+	"deleteInteraction is destructive — confirm with the user first.",
+	"Pick the RIGHT node type for an action: the wrong type resolves against nothing and the step silently no-ops.",
+	"Any param VALUE can be a data-binding token {{ source }} — e.g. addNotification content",
+	"\"{{ list_<idRef>.item.name }}\" shows the clicked row’s field; it resolves at runtime just like a prop binding.",
+	"",
+	"globalCallback (nodeType \"globalCallback\") — provided by a SOURCE MODULE, not the host element: OMIT elementId",
+	"and the MCP pins the right source and fills the builder’s param defaults. Use ONLY each callback’s declared",
+	"params (exact spelling) — for addNotification the text goes in `content` (NO title/message/type). Built-ins:",
+	...globalCallbackLines(),
+	"",
+	"callback (nodeType \"callback\") — a callback ON an element; elementId is that element (host by default). Every",
+	"element has a built-in `setState` that changes ITS OWN attribute/state (category/key/value/revertOnFinish). Set",
+	"revertOnFinish:true for a TEMPORARY change (e.g. a \"loading…\" label) so it auto-reverts at flow end — do NOT add",
+	"manual restore steps. This element setState has NO `type` param (that is the global state setState). Built-ins:",
+	...elementCallbackLines(),
+	"",
+	"utility (nodeType \"utility\") — no element/source. Use the EXACT param names (delayTime waits `time` ms, not",
+	"`delay`). Built-ins:",
+	...utilityLines(),
+	"The full param schema (types, options, defaults) for each is in plitzi://interactions/{env}."
+].join("\n");
+/** The MCP-owned guidance block a consumer concatenates into its system prompt. Covers what the MCP is
+*  authoritative about: its editing model, tools, resources and interaction vocabulary. It intentionally does NOT
+*  cover a consumer’s own tools (previews, design helpers) or product framing (modes, identity, security). */
+var buildAgentGuide = () => [
+	EDITING_MODEL,
+	"",
+	TOOLS,
+	"",
+	RESOURCES,
+	"",
+	NAVIGATION,
+	"",
+	INTERACTIONS()
+].join("\n");
+//#endregion
+export { buildAgentGuide };

package/dist/modules/mcp/helpers/computeVersion.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+//#region src/modules/mcp/helpers/computeVersion.ts
+var canonicalize = (data) => {
+	if (data === null || data === void 0) return "null";
+	if (typeof data === "string") return JSON.stringify(data);
+	if (typeof data === "number" || typeof data === "boolean") return String(data);
+	if (Array.isArray(data)) return `[${data.map(canonicalize).join(",")}]`;
+	if (typeof data === "bigint") return data.toString();
+	if (typeof data === "object") return `{${Object.keys(data).sort().map((k) => `${canonicalize(k)}:${canonicalize(data[k])}`).join(",")}}`;
+	return "null";
+};
+var computeVersion = (data) => {
+	return createHash("sha1").update(canonicalize(data)).digest("hex").slice(0, 12);
+};
+//#endregion
+export { computeVersion };