@appsoftwareltd/etherpk-mcp 0.9.6 → 0.10.0

package/dist/main.js

@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.9.6",
+	version: "0.10.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -4162,9 +4162,49 @@ function parseBlocks(markdown) {
 	return roots;
 }
 //#endregion
+//#region ../client/src/lib/document/extension-fence.ts
+/**
+* [[Extension Fence]]s (ADR 0138): a fence whose info word is `<extension id>.<name>` holds an
+* extension's data, such as a drawing's elements. Every reader of a document decides from the info
+* word alone, with no extension running, so the editor, the index, Semantic Search, the publisher
+* and the Headless Client always agree: the body is never read as writing, never searched, and never
+* published as code.
+*
+* Framework-free, so the index worker, the publisher and the Headless Client read it as the editor
+* does.
+*/
+/** An extension's id or a name under it: lowercase letters, digits and hyphens, from a letter. */
+var NAME = "[a-z][a-z0-9-]*";
+var EXTENSION_FENCE_INFO = new RegExp(`^${NAME}\\.${NAME}$`);
+/** Whether an info word names an Extension Fence: an extension's id, a dot and a name. */
+function isExtensionFenceInfo(info) {
+	return EXTENSION_FENCE_INFO.test(info);
+}
+/** The extension an Extension Fence's info word names: the part before the dot. */
+function extensionOfFence(info) {
+	return info.slice(0, info.indexOf("."));
+}
+/** Each complete, outermost Extension Fence in `lines`, by its opener's and closer's 0-based lines. */
+function extensionFences(lines) {
+	const out = [];
+	const { sorted, parent } = fencedBlockTree(fencedBlocks(lines));
+	sorted.forEach((block, i) => {
+		if (parent[i] !== -1) return;
+		const info = fenceLineInfo(lines[block.start])?.info ?? "";
+		if (isExtensionFenceInfo(info)) out.push({
+			start: block.start,
+			end: block.end,
+			info
+		});
+	});
+	return out;
+}
+//#endregion
 //#region ../client/src/lib/document/map-text.ts
 var NUMBER = String.raw`[+-]?(?:\d+(?:\.\d*)?|\.\d+)`;
 var POINT = new RegExp(String.raw`^\s*(${NUMBER})\s*,\s*(${NUMBER})\s*$`);
+/** How many of the last `@`s on a line may end its name (`readMapLine`). */
+var MAX_NAME_ENDS = 16;
 function readPoint(text) {
 	const match = POINT.exec(text);
 	if (!match) return null;
@@ -4214,7 +4254,8 @@ function readLocation(text, name) {
 function readMapLine(text) {
 	const trimmed = text.trim();
 	if (trimmed === "") return null;
-	for (let at = trimmed.lastIndexOf("@"); at >= 0; at = at === 0 ? -1 : trimmed.lastIndexOf("@", at - 1)) {
+	let tries = 0;
+	for (let at = trimmed.lastIndexOf("@"); at >= 0 && tries < MAX_NAME_ENDS; at = at === 0 ? -1 : trimmed.lastIndexOf("@", at - 1), tries++) {
 		const line = readLocation(trimmed.slice(at + 1), trimmed.slice(0, at).trim());
 		if (line) return line;
 	}
@@ -4528,30 +4569,57 @@ function deriveDoc(text) {
 	const candidateTasks = blocks.filter((b) => b.kind === "task");
 	const fenced = candidateTasks.length === 0 ? () => false : fencedLines(text);
 	const taskBlocks = candidateTasks.filter((b) => !fenced(b.startLine));
+	const tasks = taskBlocks.map((b) => {
+		const tags = parseTaskTags(b.label);
+		return {
+			blockLocalId: b.localId,
+			done: b.done ?? false,
+			text: b.label,
+			line: b.startLine,
+			priority: tags.priority,
+			waiting: tags.waiting,
+			doing: tags.doing,
+			cancelled: tags.cancelled,
+			due: tags.due,
+			completion: tags.completion,
+			scheduled: tags.scheduled
+		};
+	});
+	const maps = deriveMaps(text, blocks, links, lineToBlock);
 	return {
 		blocks,
 		links,
-		tasks: taskBlocks.map((b) => {
-			const tags = parseTaskTags(b.label);
-			return {
-				blockLocalId: b.localId,
-				done: b.done ?? false,
-				text: b.label,
-				line: b.startLine,
-				priority: tags.priority,
-				waiting: tags.waiting,
-				doing: tags.doing,
-				cancelled: tags.cancelled,
-				due: tags.due,
-				completion: tags.completion,
-				scheduled: tags.scheduled
-			};
-		}),
+		tasks,
 		taskConcepts: deriveTaskConcepts(blocks, links, taskBlocks),
-		...deriveMaps(text, blocks, links, lineToBlock)
+		...maps,
+		searchText: withoutExtensionFences(text, blocks, lineToBlock, maps.searchText)
 	};
 }
 /**
+* What search and Semantic Search read for each block holding an [[Extension Fence]] (ADR 0138):
+* the block's text with the fence's lines left out, so an extension's data (a drawing's elements)
+* never fills either index. Added to what `deriveMaps` gave, block by block.
+*/
+function withoutExtensionFences(text, blocks, lineToBlock, searchText) {
+	if (!/```[a-z][a-z0-9-]*\.[a-z]/.test(text)) return searchText;
+	const fences = extensionFences(text.split("\n"));
+	if (fences.length === 0) return searchText;
+	const hidden = /* @__PURE__ */ new Map();
+	for (const fence of fences) {
+		const id = lineToBlock.get(fence.start);
+		if (id === void 0) continue;
+		const lines = hidden.get(id) ?? /* @__PURE__ */ new Set();
+		for (let line = fence.start; line <= fence.end; line++) lines.add(line);
+		hidden.set(id, lines);
+	}
+	for (const [id, lines] of hidden) {
+		const block = blocks[id];
+		const read = (searchText.get(id) ?? block.text).split("\n").map((line, n) => lines.has(block.startLine + n) ? "" : line);
+		searchText.set(id, read.join("\n"));
+	}
+	return searchText;
+}
+/**
 * The [[Place]]s and [[Route]]s a document's [[Map Block]]s hold (ADR 0118), the [[Block
 * Concept]]s of the blocks they sit in, and what text search reads for those blocks instead of
 * their coordinates.
@@ -12651,6 +12719,13 @@ function wikilinkRule(md, resolve) {
 * grammars for code), so they are pre-rendered by the orchestrator and handed in as lookups;
 * the renderer itself is synchronous and pure over its inputs.
 */
+/** A fence an extension published, as HTML the publisher writes: the extension never writes markup into a site. */
+function fenceOutputHtml(output) {
+	if (output.kind === "picture") return `<figure class="diagram diagram-extension"><img src="${escapeHtml$3(output.src)}" alt="${escapeHtml$3(output.alt)}" width="${output.width}" height="${output.height}" loading="lazy"></figure>\n`;
+	const size = (image) => image.width && image.height ? ` width="${Math.round(image.width)}" height="${Math.round(image.height)}"` : "";
+	const image = output.image ? `<img src="${escapeHtml$3(output.image.src)}" alt="${escapeHtml$3(output.image.alt)}"${size(output.image)} loading="lazy">` : "";
+	return `<figure class="diagram diagram-link"><a href="${escapeHtml$3(output.href)}">${image}</a><figcaption><a href="${escapeHtml$3(output.href)}">${escapeHtml$3(output.text)}</a></figcaption></figure>\n`;
+}
 /** The names on a Map Block, one line for the search index and the excerpt; never its coordinates. */
 function mapNames(source) {
 	return readMapBody(source.split("\n")).items.map((item) => item.name).filter((name) => name !== "").join(", ");
@@ -12698,7 +12773,7 @@ function plainText(tokens) {
 		if (info === "map") {
 			const names = mapNames(token.content);
 			if (names !== "") lines.push(names);
-		} else if (info !== "mermaid" && info !== "math") lines.push(token.content.trim());
+		} else if (info !== "mermaid" && info !== "math" && !isExtensionFenceInfo(info)) lines.push(token.content.trim());
 	}
 	return lines.join("\n");
 }
@@ -12777,6 +12852,9 @@ function createDocumentRenderer(options) {
 			if (!picture) return "";
 			return `<figure class="map"><img src="${escapeHtml$3(picture.src)}" alt="${escapeHtml$3(picture.alt)}" width="${picture.width}" height="${picture.height}" loading="lazy"></figure>\n`;
 		}
+		const output = options.fenceOutput?.(lang, code);
+		if (output) return fenceOutputHtml(output);
+		if (output === null || isExtensionFenceInfo(lang)) return "";
 		const highlighted = options.highlighted?.(lang, code);
 		return `<pre><code${lang === "" ? "" : ` class="language-${escapeHtml$3(lang)}"`}>${highlighted ?? escapeHtml$3(code)}</code></pre>\n`;
 	};
@@ -13229,6 +13307,80 @@ async function mapPictureName(source) {
 	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${MAP_PICTURE_VERSION}\n${source}`));
 	return [...new Uint8Array(digest)].slice(0, 8).map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
+/** A fence's body as lines, as an extension's widget reads it: markdown-it's content ends with a line break. */
+function bodyLines(code) {
+	const lines = code.split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+var PICTURE_EXTENSIONS = {
+	"image/svg+xml": "svg",
+	"image/png": "png",
+	"image/webp": "webp"
+};
+/** An `https` address as written, or null for any other. */
+function httpsAddress(value) {
+	if (typeof value !== "string") return null;
+	try {
+		return new URL(value).protocol === "https:" ? value : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* What an extension's `publish` answered for a fence, checked, its picture kept for the site under
+* a name taken from its bytes: a picture, a link (`https` only, as is any picture in it), null when
+* it is left out, or undefined when it could not be made, after which an ordinary fence is published
+* as code and an Extension Fence left out, with a warning either way.
+*/
+async function publishedFence(asked, info, concept, pictures, warnings) {
+	try {
+		const out = await asked;
+		if (out === null) return null;
+		if (out.kind === "picture") {
+			const extension = PICTURE_EXTENSIONS[out.type];
+			if (!(out.bytes instanceof Uint8Array) || !extension) throw new Error("its picture is not an SVG, PNG or WebP file");
+			const digest = await crypto.subtle.digest("SHA-256", out.bytes);
+			const path = `pictures/${[...new Uint8Array(digest)].slice(0, 8).map((byte) => byte.toString(16).padStart(2, "0")).join("")}.${extension}`;
+			pictures.set(path, out.bytes);
+			return {
+				kind: "picture",
+				src: path,
+				alt: String(out.alt ?? ""),
+				width: Math.round(out.width),
+				height: Math.round(out.height)
+			};
+		}
+		if (out.kind === "link") {
+			const href = httpsAddress(out.href);
+			if (!href) throw new Error("its link is not an https address");
+			const src = httpsAddress(out.image?.src);
+			const image = src && out.image ? {
+				src,
+				alt: String(out.image.alt ?? ""),
+				width: out.image.width,
+				height: out.image.height
+			} : void 0;
+			return {
+				kind: "link",
+				href,
+				text: String(out.text ?? href),
+				...image ? { image } : {}
+			};
+		}
+		throw new Error("it answered with something that is neither a picture nor a link");
+	} catch (error) {
+		const why = error instanceof Error ? error.message : String(error);
+		const extensionFence = isExtensionFenceInfo(info);
+		warnings.push({
+			level: "warning",
+			code: "extension-fence-failed",
+			message: `A \`${info}\` block in "${concept}" could not be published: ${why}. ${extensionFence ? "It is left out." : "It is published as its text."}`,
+			concept
+		});
+		return extensionFence ? null : void 0;
+	}
+}
 function assetHrefOf(name) {
 	return `assets/${encodeURIComponent(name)}`;
 }
@@ -13407,6 +13559,10 @@ async function publishPublication(source, publication, env, options = {}) {
 	}
 	const mermaidSvg = /* @__PURE__ */ new Map();
 	const mapPictures = /* @__PURE__ */ new Map();
+	/** What each fence an extension publishes becomes, by its info word and body; null when it is left out. */
+	const fenceOutputs = /* @__PURE__ */ new Map();
+	/** The pictures extensions made of fences, by their path in the site. */
+	const fencePictures = /* @__PURE__ */ new Map();
 	const highlighted = /* @__PURE__ */ new Map();
 	const highlight = env.highlightCode ?? highlightCode;
 	const probe = createDocumentRenderer({
@@ -13417,51 +13573,77 @@ async function publishPublication(source, publication, env, options = {}) {
 		doc: d,
 		body: bodyOf$1(d)
 	}));
-	for (const { doc, body } of bodies) for (const fence of probe.fences(body)) if (fence.lang === "mermaid") {
-		if (!env.renderMermaid || mermaidSvg.has(fence.code)) continue;
-		try {
-			mermaidSvg.set(fence.code, await env.renderMermaid(fence.code));
-		} catch (error) {
+	for (const { doc, body } of bodies) for (const fence of probe.fences(body)) {
+		const fenceKey = `${fence.lang}\n${fence.code}`;
+		const extensionFence = isExtensionFenceInfo(fence.lang);
+		const asked = fence.lang === "" || fenceOutputs.has(fenceKey) ? void 0 : env.publishFence?.({
+			info: fence.lang,
+			body: bodyLines(fence.code),
+			document: doc.concept
+		});
+		if (asked) {
+			const output = await publishedFence(asked, fence.lang, doc.concept, fencePictures, warnings);
+			if (output !== void 0) {
+				fenceOutputs.set(fenceKey, output);
+				continue;
+			}
+		} else if (fenceOutputs.has(fenceKey)) continue;
+		if (extensionFence) {
+			fenceOutputs.set(fenceKey, null);
 			warnings.push({
 				level: "warning",
-				code: "mermaid-render-failed",
-				message: `A diagram in "${doc.concept}" could not be rendered: ${error instanceof Error ? error.message : String(error)}. It is left as its source for a script to draw.`,
-				concept: doc.concept
-			});
-		}
-	} else if (fence.lang === "map") {
-		if (mapPictures.has(fence.code) || errors.some((e) => e.code === "map-not-drawn" && e.concept === doc.concept)) continue;
-		if (!env.renderMap) {
-			errors.push({
-				level: "error",
-				code: "map-not-drawn",
-				message: `"${doc.concept}" holds a map, which this publisher can't draw. Publish the site from EtherPK in a browser, where maps are drawn.`,
+				code: "extension-fence-left-out",
+				message: `"${doc.concept}" holds content from the ${extensionOfFence(fence.lang)} extension, which this publisher can't draw, so it is left out. Publish from EtherPK in a browser, with that extension on, to include it.`,
 				concept: doc.concept
 			});
 			continue;
 		}
-		try {
-			const picture = await env.renderMap(fence.code);
-			const path = `maps/${await mapPictureName(fence.code)}.${picture.type === "image/webp" ? "webp" : "png"}`;
-			mapPictures.set(fence.code, {
-				...picture,
-				path,
-				alt: mapAltText(fence.code.split("\n"))
-			});
-		} catch (error) {
-			const why = error instanceof Error ? error.message : String(error);
-			errors.push({
-				level: "error",
-				code: "map-not-drawn",
-				message: `The map in "${doc.concept}" could not be drawn: ${why}. Nothing was published, so try again once it can be.`,
-				concept: doc.concept
-			});
+		if (fence.lang === "mermaid") {
+			if (!env.renderMermaid || mermaidSvg.has(fence.code)) continue;
+			try {
+				mermaidSvg.set(fence.code, await env.renderMermaid(fence.code));
+			} catch (error) {
+				warnings.push({
+					level: "warning",
+					code: "mermaid-render-failed",
+					message: `A diagram in "${doc.concept}" could not be rendered: ${error instanceof Error ? error.message : String(error)}. It is left as its source for a script to draw.`,
+					concept: doc.concept
+				});
+			}
+		} else if (fence.lang === "map") {
+			if (mapPictures.has(fence.code) || errors.some((e) => e.code === "map-not-drawn" && e.concept === doc.concept)) continue;
+			if (!env.renderMap) {
+				errors.push({
+					level: "error",
+					code: "map-not-drawn",
+					message: `"${doc.concept}" holds a map, which this publisher can't draw. Publish the site from EtherPK in a browser, where maps are drawn.`,
+					concept: doc.concept
+				});
+				continue;
+			}
+			try {
+				const picture = await env.renderMap(fence.code);
+				const path = `maps/${await mapPictureName(fence.code)}.${picture.type === "image/webp" ? "webp" : "png"}`;
+				mapPictures.set(fence.code, {
+					...picture,
+					path,
+					alt: mapAltText(fence.code.split("\n"))
+				});
+			} catch (error) {
+				const why = error instanceof Error ? error.message : String(error);
+				errors.push({
+					level: "error",
+					code: "map-not-drawn",
+					message: `The map in "${doc.concept}" could not be drawn: ${why}. Nothing was published, so try again once it can be.`,
+					concept: doc.concept
+				});
+			}
+		} else if (fence.lang !== "" && fence.lang !== "math" && fence.lang !== "etherpk-cipher") {
+			const key = `${fence.lang}\n${fence.code}`;
+			if (highlighted.has(key)) continue;
+			const html = await highlight(fence.lang, fence.code);
+			if (html !== null) highlighted.set(key, html);
 		}
-	} else if (fence.lang !== "" && fence.lang !== "math" && fence.lang !== "etherpk-cipher") {
-		const key = `${fence.lang}\n${fence.code}`;
-		if (highlighted.has(key)) continue;
-		const html = await highlight(fence.lang, fence.code);
-		if (html !== null) highlighted.set(key, html);
 	}
 	if (errors.length > 0) return {
 		bundle,
@@ -13493,7 +13675,8 @@ async function publishPublication(source, publication, env, options = {}) {
 				width: picture.width,
 				height: picture.height
 			};
-		}
+		},
+		fenceOutput: (lang, code) => fenceOutputs.get(`${lang}\n${code}`)
 	});
 	const pages = [];
 	let done = 0;
@@ -13752,6 +13935,7 @@ async function publishPublication(source, publication, env, options = {}) {
 		report.assets.copied.push(name);
 	}
 	for (const picture of mapPictures.values()) bundle.set(picture.path, picture.bytes);
+	for (const [path, bytes] of fencePictures) bundle.set(path, bytes);
 	for (const [path, text] of theme.files) if (path.startsWith("assets/")) bundle.set(`theme/${path.slice(7)}`, text);
 	if (customCss !== "") bundle.set("theme/custom.css", customCss.endsWith("\n") ? customCss : `${customCss}\n`);
 	if (hasMath) {
@@ -18498,7 +18682,7 @@ function createMcpServer(source, info) {
 	}, async (args) => run((graph) => rename$1(graph, args)));
 	server.registerTool("set_aliases", {
 		title: "Set aliases",
-		description: "Replace a document's aliases: other names it answers to in [[wikilinks]], Quick Find and on a published site. The list you pass is the complete list, and it is shown in the document's frontmatter, in a block added if there is none. A name that is already another document's title or alias is refused with error \"name_taken\".",
+		description: "Replace a document's aliases: other names it answers to in [[wikilinks]], Search and on a published site. The list you pass is the complete list, and it is shown in the document's frontmatter, in a block added if there is none. A name that is already another document's title or alias is refused with error \"name_taken\".",
 		inputSchema: {
 			concept,
 			aliases: z.array(z.string()).describe("Every alias the document should have - an empty list removes them all.")