@plitzi/sdk-mcp 0.38.7 → 0.38.8

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

@@ -0,0 +1,201 @@
+import { findElementByRef } from "../helpers/space.js";
+import { scalar } from "./operations/schema/shared.js";
+import { defineTool } from "./shared/tool.js";
+import { apply } from "./apply/index.js";
+import { closest } from "@plitzi/sdk-authoring";
+import { z } from "zod";
+//#region src/modules/mcp/tools/intents.ts
+/** The element a ref names, with the page or layout it is on — or the nearest ref there is. */
+var locate = (ctx, ref) => {
+	const element = findElementByRef(ctx.space.schema, ref);
+	if (element) return {
+		element,
+		root: element.definition.rootId,
+		classes: element.definition.styleSelectors.base.split(/\s+/).filter(Boolean)
+	};
+	const nearest = closest(ref, Object.keys(ctx.space.schema.flat));
+	return {
+		done: false,
+		errors: [{
+			path: "ref",
+			message: `There is no element "${ref}"${nearest ? ` — did you mean "${nearest}"?` : ""}`,
+			hint: "plitzi_search finds an element by its words, type or class"
+		}]
+	};
+};
+/** The attributes of an element a binding computes, with the source each reads. */
+var boundOf = (element) => new Map((element.definition.bindings?.attributes ?? []).map((binding) => [binding.to, binding.source]));
+/**
+* The batch applied, answered with what it did. `notes` are what the agent believed that was already so — a class it
+* wears, an attribute it did not have — said beside the effects, never dropped because nothing came of them.
+*/
+var run = async (ctx, operations, page, notes = []) => {
+	const result = await apply({
+		operations,
+		environment: ctx.env
+	}, ctx.space, ctx.persisters);
+	const warnings = [...notes, ...result.warnings ?? []];
+	if (!result.applied) return {
+		done: false,
+		errors: result.errors ?? (result.conflict ? [result.conflict] : []),
+		...warnings.length > 0 ? { warnings } : {}
+	};
+	return {
+		done: true,
+		saved: result.persisted !== false,
+		effects: result.effects ?? [],
+		...warnings.length > 0 ? { warnings } : {},
+		next: `plitzi_look { pageRef: "${page}" } to see it`
+	};
+};
+var setAttributesTool = defineTool({
+	name: "plitzi_set_attributes",
+	title: "Set an element’s attributes",
+	description: "Set or remove attributes of one element — its words (`content`), a link’s `href`, an image’s `src` and `alt`, a field’s `label`… — by its ref. plitzi://explain/{type} lists what a type takes.",
+	inputShape: {
+		ref: z.string().describe("The element, by its ref"),
+		set: z.record(z.string(), scalar).optional().describe("Attributes to write: { \"content\": \"Start free\" }"),
+		unset: z.array(z.string()).optional().describe("Attributes to remove")
+	},
+	access: "write",
+	run: async (input, ctx) => {
+		const at = locate(ctx, input.ref);
+		if ("done" in at) return at;
+		const set = input.set ?? {};
+		const unset = input.unset ?? [];
+		const bound = boundOf(at.element);
+		const covered = [...Object.keys(set), ...unset].filter((key) => bound.has(key));
+		if (covered.length > 0) return {
+			done: false,
+			errors: covered.map((key) => ({
+				path: key,
+				message: `${key} of ${input.ref} is bound to ${String(bound.get(key))}: the page shows what the binding computes, not a value written here`,
+				hint: "plitzi_bind_attribute changes what it reads; to write a value instead, plitzi_apply deleteBinding first"
+			}))
+		};
+		const { attributes } = at.element;
+		const notes = [...Object.entries(set).filter(([key, value]) => attributes[key] === value).map(([key, value]) => `${key} was already ${JSON.stringify(value)}`), ...unset.filter((key) => !(key in attributes)).map((key) => `${key} was not set`)];
+		const props = {
+			...set,
+			...Object.fromEntries(unset.map((key) => [key, null]))
+		};
+		return run(ctx, [{
+			type: "patchElement",
+			pageRef: at.root,
+			ref: input.ref,
+			props
+		}], at.root, notes);
+	}
+});
+var setClassesTool = defineTool({
+	name: "plitzi_set_classes",
+	title: "Add or remove an element’s classes",
+	description: "Add classes to one element, or take them off; the ones it wears and you do not name stay. A class is a definition of the space (plitzi://definitions/{env}).",
+	inputShape: {
+		ref: z.string().describe("The element, by its ref"),
+		add: z.array(z.string()).optional().describe("Classes it should also wear, by name"),
+		remove: z.array(z.string()).optional().describe("Classes it should no longer wear, by name")
+	},
+	access: "write",
+	run: async (input, ctx) => {
+		const at = locate(ctx, input.ref);
+		if ("done" in at) return at;
+		const absent = (input.remove ?? []).filter((name) => !at.classes.includes(name));
+		if (absent.length > 0) return {
+			done: false,
+			errors: absent.map((name) => {
+				const nearest = closest(name, at.classes);
+				return {
+					path: "remove",
+					message: `${input.ref} does not wear "${name}"${nearest ? ` — did you mean "${nearest}"?` : ""}; it wears ${at.classes.join(", ") || "no class"}`
+				};
+			})
+		};
+		const notes = (input.add ?? []).filter((name) => at.classes.includes(name)).map((name) => `${input.ref} already wore ${name}`);
+		const removed = new Set(input.remove ?? []);
+		const base = [...at.classes.filter((name) => !removed.has(name)), ...(input.add ?? []).filter((name) => !at.classes.includes(name))];
+		return run(ctx, [{
+			type: "patchElement",
+			pageRef: at.root,
+			ref: input.ref,
+			style: { base }
+		}], at.root, notes);
+	}
+});
+var bindAttributeTool = defineTool({
+	name: "plitzi_bind_attribute",
+	title: "Bind an element to data",
+	description: "Feed one attribute of an element from a data source — a list’s `items` from `apiContainer_products.data`, a heading’s `content` from a field. Sources: plitzi://data-sources/{env}.",
+	inputShape: {
+		ref: z.string().describe("The element, by its ref"),
+		to: z.string().describe("The attribute it feeds: \"items\", \"content\"…"),
+		source: z.string().describe("The source path, spelled in full: \"apiContainer_products.data\"")
+	},
+	access: "write",
+	run: async (input, ctx) => {
+		const at = locate(ctx, input.ref);
+		if ("done" in at) return at;
+		const was = boundOf(at.element).get(input.to);
+		return run(ctx, [{
+			type: "upsertBinding",
+			pageRef: at.root,
+			ref: input.ref,
+			category: "attributes",
+			binding: {
+				to: input.to,
+				source: input.source
+			}
+		}], at.root, was === void 0 ? [] : [`${input.ref}.${input.to} was bound to ${was}: replaced`]);
+	}
+});
+var placeComponentTool = defineTool({
+	name: "plitzi_place_component",
+	title: "Place a component",
+	description: "Place an instance of one of the space’s components inside an element, handing it its props. plitzi://schema/{env}/components lists them and what each takes.",
+	inputShape: {
+		component: z.string().describe("The component, by its ref"),
+		ref: z.string().describe("A ref for the new instance"),
+		into: z.string().describe("The element it goes inside, by its ref"),
+		props: z.record(z.string(), scalar).optional().describe("What it hands the component: { \"title\": \"Lamp\" }")
+	},
+	access: "write",
+	run: async (input, ctx) => {
+		const at = locate(ctx, input.into);
+		if ("done" in at) return at;
+		return run(ctx, [{
+			type: "upsertElement",
+			pageRef: at.root,
+			parentRef: input.into,
+			element: {
+				ref: input.ref,
+				type: "reference",
+				props: {
+					referenceType: "component",
+					referenceId: input.component,
+					...input.props
+				}
+			}
+		}], at.root);
+	}
+});
+var addPageTool = defineTool({
+	name: "plitzi_add_page",
+	title: "Add a page",
+	description: "A new page at a slug, inside a layout when the space has one for it (plitzi://schema/{env}/pages).",
+	inputShape: {
+		ref: z.string().describe("Its ref: \"pricing\""),
+		slug: z.string().describe("Its path, relative and without a leading slash: \"pricing\", \"posts/:postId\""),
+		label: z.string().optional().describe("Its name in the builder"),
+		layout: z.string().optional().describe("The layout it renders inside, by its ref")
+	},
+	access: "write",
+	run: async (input, ctx) => run(ctx, [{
+		type: "upsertPage",
+		ref: input.ref,
+		slug: input.slug,
+		...input.label ? { label: input.label } : {},
+		...input.layout ? { layout: input.layout } : {}
+	}], input.ref)
+});
+//#endregion
+export { addPageTool, bindAttributeTool, placeComponentTool, setAttributesTool, setClassesTool };

package/dist/modules/mcp/tools/look.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const lookShape: {
+    pageRef: z.ZodOptional<z.ZodString>;
+    view: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        accessibility: "accessibility";
+        html: "html";
+        both: "both";
+    }>>;
+    viewport: z.ZodOptional<z.ZodEnum<{
+        desktop: "desktop";
+        mobile: "mobile";
+        both: "both";
+    }>>;
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const lookTool: import('.').ToolDef;

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

@@ -0,0 +1,32 @@
+import { fullPage, lookAt, pageRef, viewport } from "./shared/look.js";
+import { defineTool, imageResult } from "./shared/tool.js";
+import { z } from "zod";
+//#region src/modules/mcp/tools/look.ts
+var lookShape = {
+	pageRef,
+	view: z.enum([
+		"accessibility",
+		"html",
+		"image",
+		"both"
+	]).optional().describe("How to see it. \"accessibility\" (default): the page as a screen reader and a browser agent read it — an outline of roles and names, every control with no name listed; text, and cheap. \"html\": the markup. \"image\": a PNG, for what only a picture shows — overflow, misalignment. \"both\": image and outline."),
+	viewport,
+	fullPage
+};
+var lookTool = defineTool({
+	name: "plitzi_look",
+	title: "Look at a page",
+	description: "See a saved page: its accessibility outline (default, text), its HTML, or a PNG. To see a change before saving it, plitzi_apply with `dryRun` and `look` instead.",
+	inputShape: lookShape,
+	access: "read",
+	run: async (input, ctx) => {
+		const look = await lookAt(ctx, {
+			...input,
+			view: input.view ?? "accessibility"
+		});
+		if ("refused" in look) return look.refused;
+		return look.images.length > 0 ? imageResult(look.images, look.meta) : look.meta;
+	}
+});
+//#endregion
+export { lookShape, lookTool };

package/dist/modules/mcp/tools/operations/closed.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/** A part of an operation (`an element`), closed: its fields as `shape` declares them, and no other. */
+export declare const closedObject: <Shape extends z.ZodRawShape>(owner: string, shape: Shape, listed: string) => z.ZodObject<{ -readonly [P in keyof Shape]: Shape[P]; }, z.core.$strict>;
+/** An operation's type, as its schema states it. */
+export declare const typeOf: (operation: z.ZodObject) => string;
+/** An operation, closed: its fields as declared, its description kept. */
+export declare const closed: <Shape extends z.ZodRawShape>(operation: z.ZodObject<Shape>) => z.ZodObject<{ -readonly [P in keyof Shape]: Shape[P]; }, z.core.$strict>;

package/dist/modules/mcp/tools/operations/closed.js

@@ -0,0 +1,29 @@
+import { closest } from "@plitzi/sdk-authoring";
+import { z } from "zod";
+//#region src/modules/mcp/tools/operations/closed.ts
+/**
+* Objects of the write vocabulary that refuse a field they do not have. One left out of a schema used to be dropped as
+* the batch was read — `prop` for `props` applied nothing and answered success, the one mistake an agent cannot see.
+* Refused instead, with the field meant and where every field is listed.
+*/
+/** What a field `owner` does not have is answered with: the nearest one it does, and where every one is listed. */
+var unknownFields = (owner, written, fields, listed) => {
+	return `${owner} has no field ${written.map((key) => {
+		const nearest = closest(key, fields);
+		return nearest ? `"${key}" (did you mean "${nearest}"?)` : `"${key}"`;
+	}).join(", ")}: ${listed} lists its fields`;
+};
+/** A part of an operation (`an element`), closed: its fields as `shape` declares them, and no other. */
+var closedObject = (owner, shape, listed) => {
+	const fields = Object.keys(shape);
+	return z.strictObject(shape, { error: (issue) => issue.code === "unrecognized_keys" ? unknownFields(owner, issue.keys, fields, listed) : void 0 });
+};
+/** An operation's type, as its schema states it. */
+var typeOf = (operation) => operation.shape.type instanceof z.ZodLiteral ? String(operation.shape.type.value) : "";
+/** An operation, closed: its fields as declared, its description kept. */
+var closed = (operation) => {
+	const type = typeOf(operation);
+	return closedObject(type, operation.shape, `plitzi_describe_operation { type: "${type}" }`).describe(operation.description ?? "");
+};
+//#endregion
+export { closed, closedObject, typeOf };