@plitzi/sdk-server 0.32.4 → 0.32.5

package/dist/modules/mcp/tools/operations/style/upsertDefinition.js

@@ -0,0 +1,23 @@
+import { empty } from "../../../helpers/opResult.js";
+import { defUri, defsUri, guardKind, writeStyleItem } from "./write.js";
+import { upsertCssShape } from "./shared.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/upsertDefinition.ts
+var upsertDefinitionOp = z.object({
+	type: z.literal("upsertDefinition"),
+	ref: z.string().describe("Class name you choose (kebab-case), or an existing class ref to fully replace"),
+	...upsertCssShape
+}).describe("Create a reusable style class (CSS), or fully replace it when ref exists. Apply it by attaching ref to an element via its style.base. Use patchDefinition to change only some CSS.");
+var upsertDefinition = (space, env, op) => {
+	const { type, ref, slots, ...base } = op;
+	const guard = guardKind(space.style, ref, "class");
+	if (guard) return guard;
+	writeStyleItem(space.style, ref, base, slots, "class", void 0);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [defUri(env, ref), defsUri(env)]
+	};
+};
+//#endregion
+export { upsertDefinition, upsertDefinitionOp };

package/dist/modules/mcp/tools/operations/style/upsertGlobalStyle.js

@@ -0,0 +1,23 @@
+import { empty } from "../../../helpers/opResult.js";
+import { globalUri, globalsUri, guardKind, writeStyleItem } from "./write.js";
+import { upsertCssShape } from "./shared.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/upsertGlobalStyle.ts
+var upsertGlobalStyleOp = z.object({
+	type: z.literal("upsertGlobalStyle"),
+	componentType: z.string().describe("Element type to style site-wide (e.g. \"button\"); affects ALL of that type"),
+	...upsertCssShape
+}).describe("Create or fully replace the site-wide style for an element TYPE — its CSS applies to every element of that type. To style one element only, use upsertDefinition + attach it. Use patchGlobalStyle for a partial change.");
+var upsertGlobalStyle = (space, env, op) => {
+	const { type, componentType, slots, ...base } = op;
+	const guard = guardKind(space.style, componentType, "element");
+	if (guard) return guard;
+	writeStyleItem(space.style, componentType, base, slots, "element", componentType);
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [globalUri(env, componentType), globalsUri(env)]
+	};
+};
+//#endregion
+export { upsertGlobalStyle, upsertGlobalStyleOp };

package/dist/modules/mcp/tools/operations/style/upsertStyleVariable.js

@@ -0,0 +1,22 @@
+import { empty } from "../../../helpers/opResult.js";
+import { styleVarUri, styleVarsUri } from "./write.js";
+import { styleCategory, themeValue } from "./shared.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/style/upsertStyleVariable.ts
+var upsertStyleVariableOp = z.object({
+	type: z.literal("upsertStyleVariable"),
+	category: styleCategory,
+	name: z.string().describe("Token name without the -- prefix; referenced in CSS as var(--name)"),
+	value: themeValue
+}).describe("Create or update a design token (referenced in CSS as var(--name); value may differ per light/dark).");
+var upsertStyleVariable = (space, env, op) => {
+	const group = space.style.variables[op.category] ??= {};
+	group[op.name] = op.value;
+	return {
+		...empty(),
+		updated: 1,
+		staleResources: [styleVarUri(env, op.category), styleVarsUri(env)]
+	};
+};
+//#endregion
+export { upsertStyleVariable, upsertStyleVariableOp };

package/dist/modules/mcp/tools/operations/style/write.js

@@ -0,0 +1,100 @@
+import { fail } from "../../../helpers/opResult.js";
+import { expandShorthand } from "./cssCatalog.js";
+import processSelector from "@plitzi/sdk-style/helpers/processSelector";
+//#region src/modules/mcp/tools/operations/style/write.ts
+var MODES = [
+	"desktop",
+	"tablet",
+	"mobile"
+];
+var defUri = (env, ref) => `plitzi://definitions/${env}/${ref}`;
+var defsUri = (env) => `plitzi://definitions/${env}`;
+var globalUri = (env, componentType) => `plitzi://global-styles/${env}/${componentType}`;
+var globalsUri = (env) => `plitzi://global-styles/${env}`;
+var styleVarUri = (env, category) => `plitzi://style-variables/${env}/${category}`;
+var styleVarsUri = (env) => `plitzi://style-variables/${env}`;
+var describeKind = (item) => item.type === "element" ? `a global style for every "${item.componentType}" element` : item.type === "class" ? "a reusable class definition" : "an id rule";
+var guardKind = (style, ref, want) => {
+	const clash = MODES.map((mode) => style.platform[mode][ref]).find((item) => item !== void 0 && item.type !== want);
+	if (!clash) return null;
+	const wantIsClass = want === "class";
+	return fail(wantIsClass ? "ref" : "componentType", `"${ref}" is already ${describeKind(clash)}; it cannot be edited as ${wantIsClass ? "a class definition" : "a global element style"}`, wantIsClass ? "To restyle every element of a type on purpose, use upsertGlobalStyle/patchGlobalStyle with its componentType. Otherwise pick a different class name." : "That name is a class definition — edit it with upsertDefinition/patchDefinition, or choose a different componentType.");
+};
+var slotToBlocks = (slot) => {
+	const perMode = {};
+	for (const mode of MODES) {
+		const block = {};
+		const baseCss = slot[mode];
+		if (baseCss && Object.keys(baseCss).length > 0) block.default = expandShorthand(baseCss);
+		for (const [state, dm] of Object.entries(slot.states ?? {})) if (dm[mode]) (block.states ??= {})[state] = expandShorthand(dm[mode]);
+		for (const [name, dm] of Object.entries(slot.variants ?? {})) if (dm[mode]) (block.variants ??= {})[name] = { default: expandShorthand(dm[mode]) };
+		if (Object.keys(block).length > 0) perMode[mode] = block;
+	}
+	return perMode;
+};
+var writeStyleItem = (style, ref, base, slots, itemType, componentType) => {
+	for (const mode of MODES) {
+		const attributes = {};
+		const baseBlocks = slotToBlocks(base);
+		if (baseBlocks[mode]) attributes.base = baseBlocks[mode];
+		for (const [slotName, slotDef] of Object.entries(slots ?? {})) {
+			const blocks = slotToBlocks(slotDef);
+			if (blocks[mode]) attributes[slotName] = blocks[mode];
+		}
+		if (Object.keys(attributes).length === 0) Reflect.deleteProperty(style.platform[mode], ref);
+		else {
+			const styleItem = {
+				name: ref,
+				type: itemType,
+				attributes,
+				cache: ""
+			};
+			if (componentType !== void 0) styleItem.componentType = componentType;
+			styleItem.cache = processSelector(styleItem);
+			style.platform[mode][ref] = styleItem;
+		}
+	}
+};
+var mergeCss = (base, patch) => {
+	const merged = { ...base };
+	for (const [key, value] of Object.entries(patch ?? {})) if (value === null) Reflect.deleteProperty(merged, key);
+	else merged[key] = value;
+	return Object.keys(merged).length > 0 ? merged : void 0;
+};
+var mergeDisplayMode = (base, patch) => {
+	const result = {};
+	for (const mode of MODES) {
+		const css = mergeCss(base?.[mode], patch?.[mode]);
+		if (css) result[mode] = css;
+	}
+	return result;
+};
+var mergeNamedModes = (base, patch) => {
+	const names = /* @__PURE__ */ new Set([...Object.keys(base ?? {}), ...Object.keys(patch ?? {})]);
+	const result = {};
+	for (const name of names) {
+		const dm = mergeDisplayMode(base?.[name], patch?.[name]);
+		if (Object.keys(dm).length > 0) result[name] = dm;
+	}
+	return Object.keys(result).length > 0 ? result : void 0;
+};
+var mergeSlot = (base, patch) => {
+	const merged = mergeDisplayMode(base, patch);
+	const states = mergeNamedModes(base?.states, patch.states);
+	if (states) merged.states = states;
+	const variants = mergeNamedModes(base?.variants, patch.variants);
+	if (variants) merged.variants = variants;
+	return merged;
+};
+var mergePatch = (existing, basePatch, slotsPatch) => {
+	const base = mergeSlot(existing, basePatch);
+	const slotNames = /* @__PURE__ */ new Set([...Object.keys(existing.slots ?? {}), ...Object.keys(slotsPatch ?? {})]);
+	const slots = {};
+	for (const name of slotNames) slots[name] = mergeSlot(existing.slots?.[name], slotsPatch?.[name] ?? {});
+	return {
+		base,
+		slots: Object.keys(slots).length > 0 ? slots : void 0
+	};
+};
+//#endregion
+export { MODES, defUri, defsUri, globalUri, globalsUri, guardKind, mergePatch, styleVarUri, styleVarsUri, writeStyleItem };

package/dist/modules/mcp/tools/preview.js

@@ -0,0 +1,37 @@
+import { operation } from "./operations/index.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/preview.ts
+var previewShape = {
+	pageRef: z.string().optional().describe("Page ref or id to preview; defaults to the space default page"),
+	operations: z.array(operation).max(100).optional().describe("Unsaved edits to apply to a throwaway clone before rendering, so you can preview a change WITHOUT persisting it (same op vocabulary as plitzi_apply). Omit to preview the current saved state.")
+};
+var previewTool = defineTool({
+	name: "plitzi_preview",
+	title: "Preview (HTML)",
+	description: "Render a page to a full HTML document to inspect the structure of your edits. Pass unsaved `operations` to preview a change before committing (nothing is persisted). Returns the HTML plus the page path and stateVersion. For a real rendered IMAGE that reveals visual issues like overflow, use plitzi_screenshot.",
+	inputShape: previewShape,
+	access: "read",
+	run: async (input, ctx) => {
+		if (!ctx.preview || ctx.spaceId === void 0) return {
+			error: "PREVIEW_UNAVAILABLE",
+			message: "Visual preview is not enabled on this server.",
+			hint: "Preview needs the SSR render service; it is unavailable in MCP-only mode."
+		};
+		const result = await ctx.preview.render({
+			spaceId: ctx.spaceId,
+			env: ctx.env,
+			pageRef: input.pageRef,
+			operations: input.operations
+		});
+		if (!result.ok) return result;
+		return {
+			pageRef: input.pageRef ?? "default",
+			pagePath: result.pagePath,
+			stateVersion: result.stateVersion,
+			html: result.html
+		};
+	}
+});
+//#endregion
+export { previewShape, previewTool };

package/dist/modules/mcp/tools/read.js

@@ -0,0 +1,33 @@
+import { resourceErrorMessage } from "../resources/canonical.js";
+import { readResource } from "../resources/router.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/read.ts
+var readShape = { uris: z.array(z.string()).min(1).max(50).describe("Resource URIs to read in one batch (max 50). Use the ready-made uris from search / write responses.") };
+var read = (input, space, env) => {
+	return { results: input.uris.map((uri) => {
+		const found = readResource(space, env, uri);
+		if (found) return {
+			uri,
+			stateVersion: found.stateVersion,
+			data: found.data
+		};
+		const parsed = JSON.parse(resourceErrorMessage(env, uri));
+		return {
+			uri,
+			error: parsed.error,
+			message: parsed.message,
+			hint: parsed.hint
+		};
+	}) };
+};
+var readTool = defineTool({
+	name: "plitzi_read",
+	title: "Batch read",
+	description: "Read MANY resources at once by URI — the batch alternative to opening resources one by one. Pass an array of URIs (pages, elements, definitions, variables), e.g. the ready-made uris from plitzi_search or a write response, and get them all back in a single call instead of one read per URI. Each result is { uri, stateVersion, data } or a teachable error, so one bad URI never fails the batch.",
+	inputShape: readShape,
+	access: "read",
+	run: (input, ctx) => read(input, ctx.space, ctx.env)
+});
+//#endregion
+export { read, readShape, readTool };

package/dist/modules/mcp/tools/screenshot.js

@@ -0,0 +1,83 @@
+import { operation } from "./operations/index.js";
+import { defineTool, imageResult } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/screenshot.ts
+var VIEWPORTS = {
+	desktop: {
+		label: "desktop",
+		width: 1440,
+		height: 900
+	},
+	mobile: {
+		label: "mobile",
+		width: 390,
+		height: 844
+	}
+};
+var resolveViewports = (choice) => {
+	if (choice === "both") return [VIEWPORTS.desktop, VIEWPORTS.mobile];
+	if (choice === "mobile") return [VIEWPORTS.mobile];
+	return [VIEWPORTS.desktop];
+};
+var screenshotShape = {
+	pageRef: z.string().optional().describe("Page ref or id to capture; defaults to the space default page"),
+	operations: z.array(operation).max(100).optional().describe("Unsaved edits to apply before rendering, so you can screenshot a proposed change WITHOUT persisting it (same op vocabulary as plitzi_apply). Omit to capture the current saved state."),
+	viewport: z.enum([
+		"desktop",
+		"mobile",
+		"both"
+	]).optional().describe("Which viewport(s) to capture. \"both\" catches responsive issues (e.g. overflow at one width). Default desktop.")
+};
+var screenshotTool = defineTool({
+	name: "plitzi_screenshot",
+	title: "Screenshot",
+	description: "Render a page to a real PNG image so you can SEE the visual result of your edits — overflow, misalignment and broken layout that data alone never reveals. Pass unsaved `operations` to screenshot a proposed change before committing, and viewport \"both\" to compare desktop and mobile. Returns the image(s).",
+	inputShape: screenshotShape,
+	access: "read",
+	requires: "screenshot",
+	run: async (input, ctx) => {
+		if (!ctx.preview || ctx.spaceId === void 0) return {
+			error: "PREVIEW_UNAVAILABLE",
+			message: "Visual preview is not enabled on this server.",
+			hint: "Preview needs the SSR render service; it is unavailable in MCP-only mode."
+		};
+		const pv = await ctx.preview.render({
+			spaceId: ctx.spaceId,
+			env: ctx.env,
+			pageRef: input.pageRef,
+			operations: input.operations
+		});
+		if (!pv.ok) return pv;
+		const viewports = resolveViewports(input.viewport);
+		if (!ctx.screenshot) return {
+			warning: "SCREENSHOT_DISABLED",
+			message: "The screenshot service is not configured; returning the HTML preview instead.",
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			html: pv.html
+		};
+		const shot = await ctx.screenshot.capture({
+			pagePath: pv.pagePath,
+			token: pv.token,
+			viewports
+		});
+		if (!shot.ok) return {
+			warning: "SCREENSHOT_UNAVAILABLE",
+			message: `The screenshot service failed (${shot.message}); returning the HTML preview instead.`,
+			hint: "The dedicated browser service is down or unreachable. Inspect the HTML, or retry later.",
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			html: pv.html
+		};
+		return imageResult(shot.images, {
+			pageRef: input.pageRef ?? "default",
+			pagePath: pv.pagePath,
+			stateVersion: pv.stateVersion,
+			viewports: viewports.map((v) => v.label)
+		});
+	}
+});
+//#endregion
+export { screenshotShape, screenshotTool };

package/dist/modules/mcp/tools/search.js

@@ -0,0 +1,108 @@
+import { computeVersion } from "../helpers/computeVersion.js";
+import { elementRefOf, getPageElements, isPageElement, pageRefOf, pageRefOfElement } from "../helpers/space.js";
+import { definitionRefs, definitionToAI } from "./operations/style/translator.js";
+import { elementDetailToAI, pageSkeletonToAI } from "./operations/schema/translator.js";
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/search.ts
+var searchShape = {
+	query: z.string().describe("Case-insensitive match on label, type and attribute values"),
+	filters: z.object({
+		type: z.string().optional(),
+		pageRef: z.string().optional()
+	}).optional(),
+	include: z.literal("detail").optional().describe("Set to \"detail\" to inline each hit's full props/style so an edit needs no follow-up read"),
+	limit: z.number().int().min(1).max(100).optional().describe("Max element hits to return (default 50). Response echoes total and, if more remain, nextOffset."),
+	offset: z.number().int().min(0).optional().describe("Element hits to skip (default 0). Page by re-calling with offset = nextOffset until it is absent.")
+};
+var labelOf = (el) => (typeof el.attributes.name === "string" ? el.attributes.name : void 0) ?? el.definition.label;
+var breadcrumb = (schema, el) => {
+	const chain = [];
+	let current = el;
+	const guard = /* @__PURE__ */ new Set();
+	while (current && !guard.has(current.id)) {
+		guard.add(current.id);
+		chain.push(labelOf(current));
+		current = current.definition.parentId ? schema.flat[current.definition.parentId] : void 0;
+	}
+	return chain.reverse();
+};
+var search = (input, space, env) => {
+	const query = input.query.toLowerCase();
+	const results = [];
+	for (const el of Object.values(space.schema.flat)) {
+		if (isPageElement(space.schema, el)) continue;
+		if (input.filters?.type && el.definition.type !== input.filters.type) continue;
+		const pageRef = pageRefOfElement(space.schema, el);
+		if (input.filters?.pageRef && pageRef !== input.filters.pageRef) continue;
+		const matches = [];
+		if (el.definition.label.toLowerCase().includes(query)) matches.push(`label: ${el.definition.label}`);
+		if (el.definition.type.toLowerCase().includes(query)) matches.push(`type: ${el.definition.type}`);
+		for (const [key, value] of Object.entries(el.attributes)) if (String(value).toLowerCase().includes(query)) matches.push(`${key}: ${String(value).slice(0, 100)}`);
+		if (matches.length === 0) continue;
+		const ref = elementRefOf(el);
+		const detail = elementDetailToAI(space.schema, el, space.style);
+		results.push({
+			pageRef,
+			ref,
+			uri: `plitzi://schema/${env}/elements/${ref}`,
+			pageUri: `plitzi://schema/${env}/pages/${pageRef}`,
+			stateVersion: computeVersion(detail),
+			parentRef: detail.parentRef,
+			path: breadcrumb(space.schema, el),
+			label: el.definition.label,
+			type: el.definition.type,
+			matches,
+			detail: input.include === "detail" ? detail : void 0
+		});
+	}
+	const definitions = [];
+	for (const ref of definitionRefs(space.style)) {
+		if (ref.toLowerCase().includes(query)) {
+			const def = definitionToAI(space.style, ref);
+			if (def) definitions.push(def);
+		}
+		if (definitions.length >= 50) break;
+	}
+	const pages = [];
+	for (const page of getPageElements(space.schema)) {
+		const label = labelOf(page);
+		const slug = typeof page.attributes.slug === "string" ? page.attributes.slug : "";
+		const matches = [];
+		if (label.toLowerCase().includes(query)) matches.push(`label: ${label}`);
+		if (slug && slug.toLowerCase().includes(query)) matches.push(`slug: ${slug}`);
+		if (matches.length === 0) continue;
+		const ref = pageRefOf(page);
+		pages.push({
+			ref,
+			uri: `plitzi://schema/${env}/pages/${ref}`,
+			stateVersion: computeVersion(pageSkeletonToAI(space.schema, page)),
+			label,
+			slug,
+			matches
+		});
+	}
+	const offset = input.offset ?? 0;
+	const limit = input.limit ?? 50;
+	const total = results.length;
+	const nextOffset = offset + limit < total ? offset + limit : void 0;
+	return {
+		results: results.slice(offset, offset + limit),
+		total,
+		offset,
+		limit,
+		nextOffset,
+		definitions: definitions.length > 0 ? definitions : void 0,
+		pages: pages.length > 0 ? pages : void 0
+	};
+};
+var searchTool = defineTool({
+	name: "plitzi_search",
+	title: "Search",
+	description: "Find elements by label, type or attribute value across all pages. Each hit returns the element uri, its stateVersion (edit with optimistic concurrency, no read needed) and its tree path. Pass include: \"detail\" to inline the full props/style of each hit plus resolvedStyle (the CSS of its classes). Also returns any style definitions matching the query (with full CSS) under `definitions`, and matching pages under `pages`. Element hits are paginated: it returns at most `limit` (default 50) starting at `offset`, plus `total` and — while more remain — `nextOffset` to fetch the next page.",
+	inputShape: searchShape,
+	access: "read",
+	run: (input, ctx) => search(input, ctx.space, ctx.env)
+});
+//#endregion
+export { search, searchShape, searchTool };

package/dist/modules/mcp/tools/shared/tool.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+//#region src/modules/mcp/tools/shared/tool.ts
+/** Build the MCP CallToolResult for an image-returning tool: a text meta block followed by one image block per
+*  PNG, so a vision-capable agent (or MCP client) sees the render directly. */
+var imageResult = (images, meta) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(meta)
+}, ...images.map((img) => ({
+	type: "image",
+	data: img.data,
+	mimeType: img.mimeType
+}))] });
+/** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
+*  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.
+*  Adding a tool is: call defineTool in its own file and append it to the `tools` registry. */
+var defineTool = (spec) => ({
+	name: spec.name,
+	title: spec.title,
+	description: spec.description,
+	inputShape: spec.inputShape,
+	access: spec.access,
+	requires: spec.requires,
+	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
+});
+//#endregion
+export { defineTool, imageResult };