@plitzi/sdk-server 0.32.24 → 0.33.0

package/dist/modules/mcp/proxy/guard.js

@@ -1,38 +0,0 @@
-import { lookup } from "node:dns/promises";
-import { isIP } from "node:net";
-//#region src/modules/mcp/proxy/guard.ts
-var isPrivateIpv4 = (address) => {
-	const parts = address.split(".").map(Number);
-	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return true;
-	const [a = 0, b = 0] = parts;
-	return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 0 || a === 192 && b === 168 || a === 198 && (b === 18 || b === 19) || a >= 224;
-};
-var isPrivateIpv6 = (address) => {
-	const normalized = address.toLowerCase().split("%")[0] ?? "";
-	if (normalized.startsWith("::ffff:") && normalized.includes(".")) return isPrivateIpv4(normalized.slice(7));
-	return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
-};
-var isPrivateAddress = (address) => isIP(address) === 6 ? isPrivateIpv6(address) : isPrivateIpv4(address);
-var PRIVATE_SUFFIXES = [
-	".local",
-	".internal",
-	".localhost",
-	".home.arpa"
-];
-/** Does this hostname resolve somewhere on the public internet? The endpoint fetches URLs an agent authored, so
-*  without this it would be a way to read whatever the pod itself can reach — the cluster's services, the cloud
-*  metadata endpoint, a database on the node. Both the literal address and every address the name resolves to are
-*  checked; a name that does not resolve is refused rather than handed to fetch. */
-var isPublicHost = async (hostname) => {
-	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-	if (!host || host === "localhost" || PRIVATE_SUFFIXES.some((suffix) => host.endsWith(suffix))) return false;
-	if (isIP(host)) return !isPrivateAddress(host);
-	try {
-		const addresses = await lookup(host, { all: true });
-		return addresses.length > 0 && addresses.every((entry) => !isPrivateAddress(entry.address));
-	} catch {
-		return false;
-	}
-};
-//#endregion
-export { isPrivateAddress, isPublicHost };

package/dist/modules/mcp/proxy/handler.js

@@ -1,68 +0,0 @@
-import { readGrant } from "./grant.js";
-import { fetchResource } from "./fetch.js";
-//#region src/modules/mcp/proxy/handler.ts
-var CACHE_CONTROL = {
-	asset: "public, max-age=86400, immutable",
-	data: "no-store"
-};
-var fail = (res, status, reason) => {
-	res.setStatus(status);
-	res.setHeader("Content-Type", "text/plain; charset=utf-8");
-	res.setHeader("Cache-Control", "no-store");
-	res.send(reason);
-};
-/** Serve one external resource on behalf of a widget: check the grant this server signed, fetch the target, and
-*  stream it back under this origin — the one the CSP declares. Read-only, credential-free and CORS-open, because
-*  it answers the host's sandboxed iframe: a browser that has no origin of its own and can present nothing. The
-*  grant is what stands in for a caller identity — it is unforgeable, it names one target (or one host, for a
-*  templated API URL), it names the kind, it expires, and it carries the connection that minted it. */
-var handleProxyRequest = async (req, res, settings) => {
-	res.setHeader("Access-Control-Allow-Origin", "*");
-	res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
-	if (req.method === "OPTIONS") {
-		res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
-		res.setHeader("Access-Control-Allow-Headers", "*");
-		res.setStatus(204);
-		res.end();
-		return;
-	}
-	if (req.method !== "GET" && req.method !== "HEAD") {
-		fail(res, 405, "Only GET is served here.");
-		return;
-	}
-	const grant = readGrant(req.query["i"], settings.secret);
-	if (!grant) {
-		fail(res, 403, "This URL is missing a grant, or the one it carries was not issued here or has expired.");
-		return;
-	}
-	const result = await fetchResource(grant.target, grant.kind, settings.maxBytes);
-	if (!result.ok) {
-		fail(res, result.status, result.reason);
-		return;
-	}
-	res.setStatus(200);
-	res.setHeader("Content-Type", result.contentType);
-	res.setHeader("Cache-Control", CACHE_CONTROL[grant.kind]);
-	if (req.method === "HEAD" || !result.body) {
-		res.end();
-		return;
-	}
-	const reader = result.body.getReader();
-	let written = 0;
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			written += value.byteLength;
-			if (written > settings.maxBytes) {
-				await reader.cancel();
-				break;
-			}
-			res.write(Buffer.from(value));
-		}
-	} finally {
-		res.end();
-	}
-};
-//#endregion
-export { handleProxyRequest };

package/dist/modules/mcp/proxy/rewrite.js

@@ -1,72 +0,0 @@
-import { grantUrl, isGranted, isRemote } from "./grant.js";
-//#region src/modules/mcp/proxy/rewrite.ts
-var URL_ATTRIBUTES = ["src", "poster"];
-var MARKUP_ATTRIBUTES = ["content", "html"];
-var FETCHING_TYPE = "apiContainer";
-var CSS_URL = /url\(\s*(["']?)(https?:\/\/[^"')\s]+)\1\s*\)/gi;
-var HTML_SRC = /(<[^>]+?\ssrc\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
-var MARKDOWN_IMAGE = /(!\[[^\]]*\]\(\s*)(https?:\/\/[^\s)]+)/gi;
-var unescapeHtml = (url) => url.replace(/&amp;/g, "&");
-var toProxy = (url, proxy) => isGranted(url, proxy) ? url : grantUrl(unescapeHtml(url), proxy);
-/** Rewrite every remote URL embedded in a string: `url(…)` in CSS, `src="…"` in markup, `![](…)` in markdown. */
-var rewriteText = (text, proxy) => text.replace(CSS_URL, (_match, quote, url) => `url(${quote}${toProxy(url, proxy)}${quote})`).replace(HTML_SRC, (_match, prefix, quote, url) => `${prefix}${quote}${toProxy(url, proxy)}${quote}`).replace(MARKDOWN_IMAGE, (_match, prefix, url) => `${prefix}${toProxy(url, proxy)}`);
-var rewriteStyleObject = (styleObject, proxy) => {
-	for (const [property, value] of Object.entries(styleObject)) if (typeof value === "string" && value.includes("url(")) styleObject[property] = rewriteText(value, proxy);
-};
-var rewriteStyleBlock = (block, proxy) => {
-	if (block.default) rewriteStyleObject(block.default, proxy);
-	for (const state of Object.values(block.states ?? {})) rewriteStyleObject(state, proxy);
-};
-/** Why a fetching element's URL was left as authored, or undefined when it can be granted. Each case is one this
-*  hop cannot reproduce faithfully, and getting it wrong silently would be worse than the request being blocked:
-*  a write sent through a GET, or an API answering 401 because its credential was dropped on the way. */
-var unproxyableFetch = (element) => {
-	const { method, headers, accessToken } = element.attributes;
-	if (typeof method === "string" && method.toLowerCase() !== "get") return `it is a ${method.toUpperCase()} request`;
-	if (typeof accessToken === "string" && accessToken !== "") return "it sends its own credentials";
-	return headers && Object.keys(headers).length > 0 ? "it sends its own headers" : void 0;
-};
-var rewriteSchema = (schema, proxy, warnings) => {
-	for (const element of Object.values(schema.flat)) {
-		const attributes = element.attributes;
-		for (const name of URL_ATTRIBUTES) {
-			const value = attributes[name];
-			if (typeof value === "string" && isRemote(value) && !isGranted(value, proxy)) attributes[name] = grantUrl(value, proxy);
-		}
-		for (const name of MARKUP_ATTRIBUTES) {
-			const value = attributes[name];
-			if (typeof value === "string" && value.includes("http")) attributes[name] = rewriteText(value, proxy);
-		}
-		const query = attributes.query;
-		if (element.definition.type !== FETCHING_TYPE || typeof query !== "string" || !isRemote(query)) continue;
-		const blocked = unproxyableFetch(element);
-		if (blocked) {
-			warnings.push(`The ${FETCHING_TYPE} "${element.idRef ?? element.id}" calls its endpoint directly because ${blocked}, so that request is subject to the network policy of the surface it renders in, and to the CORS headers of the API, and may not run. A plain GET with no headers is fetched by the widget server instead, which always works.`);
-			continue;
-		}
-		if (!isGranted(query, proxy)) attributes.query = grantUrl(query, proxy, "data");
-	}
-};
-var rewriteStyle = (style, proxy) => {
-	for (const items of Object.values(style.platform)) for (const item of Object.values(items)) {
-		for (const selector of Object.values(item.attributes)) {
-			rewriteStyleBlock(selector, proxy);
-			for (const variant of Object.values(selector.variants ?? {})) rewriteStyleBlock(variant, proxy);
-		}
-		if (item.cache.includes("url(")) item.cache = rewriteText(item.cache, proxy);
-	}
-	if (style.cache.includes("url(")) style.cache = rewriteText(style.cache, proxy);
-};
-/** Point everything an authored widget loads from outside — images, media, fonts, and the data an apiContainer
-*  fetches — at this server's endpoint, in place. The AGENT never sees this: it authors the real URL and this runs
-*  afterwards, on the throwaway space a render builds (so nothing shared is mutated) and before the global style
-*  cache is compiled (so the concatenated CSS comes out already rewritten). Returns what could not be rewritten,
-*  which is the only part the model hears about. */
-var proxifyResources = (space, proxy) => {
-	const warnings = [];
-	rewriteSchema(space.schema, proxy, warnings);
-	rewriteStyle(space.style, proxy);
-	return warnings;
-};
-//#endregion
-export { proxifyResources, rewriteText };

package/dist/modules/mcp/proxy/sign.js

@@ -1,15 +0,0 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
-//#region src/modules/mcp/proxy/sign.ts
-var SIGNATURE_LENGTH = 22;
-var sign = (payload, secret) => createHmac("sha256", secret).update(payload).digest("base64url").slice(0, SIGNATURE_LENGTH);
-var verify = (payload, signature, secret) => {
-	const expected = Buffer.from(sign(payload, secret));
-	const given = Buffer.from(signature);
-	return expected.length === given.length && timingSafeEqual(expected, given);
-};
-/** A short, stable fingerprint of the MCP credential a request carried — the connection a grant belongs to.
-*  Derived through the same secret, so it identifies without echoing any part of the token; a request with no
-*  credential (the public widgets surface) gets the shared anonymous identity. */
-var connectionId = (authorization, secret) => authorization ? sign(`id:${authorization}`, secret).slice(0, 10) : "anon";
-//#endregion
-export { connectionId, sign, verify };

package/dist/modules/mcp/proxy/types.js

@@ -1,9 +0,0 @@
-//#region src/modules/mcp/proxy/types.ts
-/** The tools a proxy may be handed to. `plitzi_render` alone by default, and that default is a guard, not a
-*  convenience: a render is a THROWAWAY widget, so rewriting its URLs changes nothing that outlives the call —
-*  while plitzi_apply writes to the user's real space, where a rewritten URL would be PERSISTED and the space
-*  would come to depend on this server's endpoint for content it owns. Nothing else should be added here without
-*  that being the intention. */
-var DEFAULT_PROXY_TOOLS = ["plitzi_render"];
-//#endregion
-export { DEFAULT_PROXY_TOOLS };

package/dist/modules/mcp/resources/canonical.js

@@ -1,30 +0,0 @@
-import { afterPrefix, aliasedRoots, itemTemplates, primerUri } from "../helpers/uris.js";
-//#region src/modules/mcp/resources/canonical.ts
-var canonicalUri = (env, uri) => {
-	const rest = afterPrefix(uri, `plitzi://schema/${env}/`);
-	if (rest === void 0) return uri;
-	for (const root of aliasedRoots) {
-		if (rest === root) return `plitzi://${root}/${env}`;
-		if (rest.startsWith(`${root}/`)) return `plitzi://${root}/${env}/${rest.slice(root.length + 1)}`;
-	}
-	return uri;
-};
-/** Teachable message for a URI that read as null. Distinguishes a well-formed URI whose ref does not resolve (the
-*  resource may be stale/deleted) from a URI whose shape matches no template at all (malformed — echo the valid
-*  templates so the agent stops hand-building URIs). See RFC 0004 I2. */
-var resourceErrorMessage = (env, uri) => {
-	const canonical = canonicalUri(env, uri);
-	if (itemTemplates(env).some((tpl) => canonical.startsWith(tpl.slice(0, tpl.lastIndexOf("/") + 1)))) return JSON.stringify({
-		error: "NOT_FOUND",
-		message: `No resource at '${uri}'. Its shape is valid but the ref does not resolve.`,
-		hint: "It may have been deleted or your URI is stale. Re-list the parent resource (pages/definitions) to refresh."
-	});
-	return JSON.stringify({
-		error: "MALFORMED_URI",
-		message: `'${uri}' matches no resource template.`,
-		hint: "Do not hand-build element URIs — take the ready-made uri from plitzi_search or a write response.",
-		validTemplates: [primerUri(env), ...itemTemplates(env)]
-	});
-};
-//#endregion
-export { canonicalUri, resourceErrorMessage };

package/dist/modules/mcp/resources/core.js

@@ -1,18 +0,0 @@
-import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
-import { buildTypeRegistry } from "../catalogs/registry.js";
-import "../helpers/uris.js";
-import { guideText } from "../helpers/guide.js";
-import { envelope } from "./envelope.js";
-//#region src/modules/mcp/resources/core.ts
-/** Space-independent singletons: the usage guide, the observed type registry and the CSS property catalog.
-*  Returns undefined when the URI is not one of these, so the router falls through to the next resolver. */
-var readCoreResource = (space, uri) => {
-	if (uri === "plitzi://guide") return envelope(guideText);
-	if (uri === "plitzi://types") return envelope(buildTypeRegistry(space.schema, space.catalog));
-	if (uri === "plitzi://css-properties") return envelope({
-		properties: cssProperties,
-		shorthands: cssShorthands
-	});
-};
-//#endregion
-export { readCoreResource };

package/dist/modules/mcp/resources/envelope.js

@@ -1,14 +0,0 @@
-import { computeVersion } from "../helpers/computeVersion.js";
-//#region src/modules/mcp/resources/envelope.ts
-/** Wrap any read projection with the version its optimistic-concurrency checks key on. */
-var envelope = (data) => ({
-	stateVersion: computeVersion(data),
-	data
-});
-var jsonContents = (uri, data) => ({ contents: [{
-	uri,
-	mimeType: "application/json",
-	text: JSON.stringify(data)
-}] });
-//#endregion
-export { envelope, jsonContents };

package/dist/modules/mcp/resources/primer.js

@@ -1,31 +0,0 @@
-import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
-import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/observed.js";
-import { buildTypeRegistry } from "../catalogs/registry.js";
-import { guideQuickstart } from "../helpers/guide.js";
-import { envelope } from "./envelope.js";
-import { definitionRefs, styleVariablesToAI } from "../tools/operations/style/translator.js";
-import { foldersToAI, pageSummariesToAI, schemaVariablesToAI, settingsToAI } from "../tools/operations/schema/translator.js";
-//#region src/modules/mcp/resources/primer.ts
-/** The cold-start bundle: everything the guide says to read before the first write, in one round-trip.
-*  Summaries only — never full page/element trees (those are opened on demand), so it stays cheap even on a
-*  large space. Carries the condensed `guideQuickstart` (not the full guideText, which the agent reads on demand at
-*  plitzi://guide) to keep the bundle small. Returns undefined when the URI is not the primer. */
-var readPrimerResource = (space, env, uri) => {
-	if (uri !== `plitzi://primer/${env}`) return;
-	return envelope({
-		guide: guideQuickstart,
-		types: buildTypeRegistry(space.schema, space.catalog),
-		cssProperties,
-		cssShorthands,
-		pages: pageSummariesToAI(space.schema),
-		folders: foldersToAI(space.schema),
-		definitions: definitionRefs(space.style),
-		styleVariables: styleVariablesToAI(space.style),
-		schemaVariables: schemaVariablesToAI(space.schema, false),
-		settings: settingsToAI(space.schema),
-		interactions: buildInteractionCatalog(space.schema),
-		dataSources: buildDataSourceCatalog(space.schema)
-	});
-};
-//#endregion
-export { readPrimerResource };

package/dist/modules/mcp/resources/register.js

@@ -1,190 +0,0 @@
-import { cssProperties, cssShorthands } from "../catalogs/cssCatalog/index.js";
-import { guideText } from "../helpers/guide.js";
-import { resourceErrorMessage } from "./canonical.js";
-import { envelope, jsonContents } from "./envelope.js";
-import { registerRenderResources } from "./renderGuide.js";
-import { readResource } from "./router.js";
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-//#region src/modules/mcp/resources/register.ts
-/** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
-*  loaded lazily via getSpace, so listing resources never touches the store — only reading one does.
-*
-*  `hasSpace` is false when the connection reaches no space (a guest / widgets-only grant): the space-dependent
-*  families are then not registered at all, so the catalog the agent browses holds only what it can actually
-*  open — no listing that answers every read with the same refusal. */
-var registerResources = (server, getSpace, env, log, hasSpace) => {
-	const emit = async (uri) => {
-		const start = performance.now();
-		try {
-			const result = readResource(await getSpace(), env, uri);
-			if (!result) throw new Error(resourceErrorMessage(env, uri));
-			log.resourceRead(uri, performance.now() - start);
-			return jsonContents(uri, result);
-		} catch (error) {
-			log.resourceRead(uri, performance.now() - start, error);
-			throw error;
-		}
-	};
-	const emitStatic = (uri, read) => {
-		const start = performance.now();
-		const result = read();
-		log.resourceRead(uri, performance.now() - start);
-		return result;
-	};
-	server.registerResource("Guide", "plitzi://guide", {
-		description: "How to read and write this space with mcp-ai",
-		mimeType: "text/markdown"
-	}, () => emitStatic("plitzi://guide", () => ({ contents: [{
-		uri: "plitzi://guide",
-		mimeType: "text/markdown",
-		text: guideText
-	}] })));
-	server.registerResource("CSS properties", "plitzi://css-properties", {
-		description: "Valid kebab-case CSS property keys, plus the shorthands that are accepted and auto-expanded",
-		mimeType: "application/json"
-	}, () => emitStatic("plitzi://css-properties", () => jsonContents("plitzi://css-properties", envelope({
-		properties: cssProperties,
-		shorthands: cssShorthands
-	}))));
-	registerRenderResources(server, log);
-	if (!hasSpace) return;
-	const fixed = [
-		[
-			"Primer",
-			`plitzi://primer/${env}`,
-			"Read this FIRST. Cold-start bundle in one call: guide, types, css-properties and SUMMARIES of pages, definitions and variables — summaries only, never full page/element trees, so it stays small even on a large space. Open a page or element on demand afterwards."
-		],
-		[
-			"Element types",
-			"plitzi://types",
-			"Observed element types with props, slots and subTypes"
-		],
-		[
-			"Pages",
-			`plitzi://schema/${env}/pages`,
-			"Page summaries (ref, label, elementCount) — no element trees"
-		],
-		[
-			"Folders",
-			`plitzi://folders/${env}`,
-			"Page folders (the sidebar tree): ref, name, slug, parentId"
-		],
-		[
-			"Style definitions",
-			`plitzi://definitions/${env}`,
-			"Style definition refs (names)"
-		],
-		[
-			"Global styles",
-			`plitzi://global-styles/${env}`,
-			"Element types that have a site-wide global style"
-		],
-		[
-			"Id styles",
-			`plitzi://id-styles/${env}`,
-			"DOM ids that have an id rule (#id) targeting a single element"
-		],
-		[
-			"Style variables",
-			`plitzi://style-variables/${env}`,
-			"Design tokens by category"
-		],
-		[
-			"Schema variables",
-			`plitzi://schema-variables/${env}`,
-			"Space-level values referenced via {{name}}"
-		],
-		[
-			"Settings",
-			`plitzi://settings/${env}`,
-			"Space-level settings: global customCss and state/auth configuration"
-		],
-		[
-			"Interactions catalog",
-			`plitzi://interactions/${env}`,
-			"Interaction actions (observed, grouped by node type) plus the built-in vocabularies — globalCallbacks (with their source module), element callbacks and utilities — each with its full param schema, the vocabulary for upsertInteractionFlow"
-		],
-		[
-			"Data sources catalog",
-			`plitzi://data-sources/${env}`,
-			"Data-source paths and binding targets observed in this space — the vocabulary for upsertBinding"
-		],
-		[
-			"Style definitions (schema alias)",
-			`plitzi://schema/${env}/definitions`,
-			"Alias of plitzi://definitions/{env}"
-		],
-		[
-			"Style variables (schema alias)",
-			`plitzi://schema/${env}/style-variables`,
-			"Alias of plitzi://style-variables/{env}"
-		],
-		[
-			"Schema variables (schema alias)",
-			`plitzi://schema/${env}/schema-variables`,
-			"Alias of plitzi://schema-variables/{env}"
-		]
-	];
-	for (const [name, uri, description] of fixed) server.registerResource(name, uri, {
-		description,
-		mimeType: "application/json"
-	}, () => emit(uri));
-	const templates = [
-		[
-			"Page",
-			`plitzi://schema/${env}/pages/{ref}`,
-			"One page as a skeleton tree (ref/type/label/children), no props"
-		],
-		[
-			"Page styles",
-			`plitzi://schema/${env}/pages/{ref}/styles`,
-			"Every style a page uses in one read: class definitions its elements attach (with CSS) + global styles"
-		],
-		[
-			"Element",
-			`plitzi://schema/${env}/elements/{ref}`,
-			"One element in full detail (props, style) by ref or id"
-		],
-		[
-			"Folder",
-			`plitzi://folders/${env}/{ref}`,
-			"One page folder (name, slug, parentId) by folder id"
-		],
-		[
-			"Style definition",
-			`plitzi://definitions/${env}/{ref}`,
-			"One style definition (CSS) by class ref"
-		],
-		[
-			"Global style",
-			`plitzi://global-styles/${env}/{componentType}`,
-			"The site-wide CSS applied to every element of one type"
-		],
-		[
-			"Id style",
-			`plitzi://id-styles/${env}/{targetId}`,
-			"The CSS of an id rule (#id) targeting a single element"
-		],
-		[
-			"Style variables by category",
-			`plitzi://style-variables/${env}/{category}`,
-			"Design tokens for one category"
-		],
-		[
-			"Style definition (schema alias)",
-			`plitzi://schema/${env}/definitions/{ref}`,
-			"Alias of plitzi://definitions/{env}/{ref}"
-		],
-		[
-			"Style variables by category (schema alias)",
-			`plitzi://schema/${env}/style-variables/{category}`,
-			"Alias of plitzi://style-variables/{env}/{category}"
-		]
-	];
-	for (const [name, tpl, description] of templates) server.registerResource(name, new ResourceTemplate(tpl, { list: void 0 }), {
-		description,
-		mimeType: "application/json"
-	}, (uri) => emit(uri.href));
-};
-//#endregion
-export { registerResources };