@appsoftwareltd/etherpk-mcp 0.9.6 → 0.10.1

package/dist/main.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { createInterface } from "node:readline/promises";
 import { availableParallelism, homedir, hostname, tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import nodePath, { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { access, chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.9.6",
+	version: "0.10.1",
 	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) {
@@ -14663,6 +14847,45 @@ async function writePublishFolders(path, folders) {
 function publishFolderOf(folders, graphKey, publicationId) {
 	return folders.folders[graphKey]?.[publicationId] ?? null;
 }
+/**
+* How two absolute folder paths relate, by the platform's own `relative` rather than by splitting
+* on `/` (Windows paths use `\`, and a shared prefix such as `notes` and `notes-site` is not a
+* parent). Spelling only: {@link publishFolderOverlap} resolves symbolic links first.
+*/
+function relateFolders(graphFolder, publishFolder, options = {}) {
+	const path = options.path ?? nodePath;
+	const caseInsensitive = options.caseInsensitive ?? (process.platform === "darwin" || process.platform === "win32");
+	const fold = (p) => caseInsensitive ? path.resolve(p).toLowerCase() : path.resolve(p);
+	const graph = fold(graphFolder);
+	const site = fold(publishFolder);
+	const below = (from, to) => {
+		const rel = path.relative(from, to);
+		return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+	};
+	if (path.relative(graph, site) === "") return "same";
+	if (below(graph, site)) return "inside";
+	if (below(site, graph)) return "contains";
+	return null;
+}
+/**
+* A path with its symbolic links resolved, for a folder that may not exist yet: the nearest
+* existing ancestor is resolved and the rest appended, so `--out ./site` under a linked parent is
+* compared where it will really be written.
+*/
+async function canonicalFolder(folder) {
+	const absolute = resolve(folder);
+	try {
+		return await realpath(absolute);
+	} catch {
+		const parent = dirname(absolute);
+		if (parent === absolute) return absolute;
+		return join(await canonicalFolder(parent), basename(absolute));
+	}
+}
+/** {@link relateFolders} over the folders as they are on disk, symbolic links followed. */
+async function publishFolderOverlap(graphFolder, publishFolder) {
+	return relateFolders(await canonicalFolder(graphFolder), await canonicalFolder(publishFolder));
+}
 /** The same file with one publication's folder set (made absolute) - the caller writes it. */
 function withPublishFolder(folders, graphKey, publicationId, folder) {
 	return { folders: {
@@ -17395,6 +17618,26 @@ async function findPublication(graph, id, host) {
 	if (!found) throw publicationNotFound(id, publications, via);
 	return found;
 }
+var OVERLAP_WORDS = {
+	same: "is the folder of",
+	inside: "is inside the folder of",
+	contains: "holds the folder of"
+};
+/**
+* Refuse a Publish Folder that overlaps a served folder: the graph's own folder, one inside it, or
+* one holding it. A publish deletes the files it did not write from the folder it writes into
+* (`isOwnedPath`), which would take the graph's attachments, or mix the site's files into the
+* graph. Checked where a folder is set (`--out`) and again before every publish, since the
+* folder may have been set before this check existed. A synced graph has no folder here.
+*/
+async function checkPublishFolder(graph, publicationId, folder, host) {
+	if (graph.backend.kind !== "folder") return;
+	const overlap = await publishFolderOverlap(graph.backend.path, folder);
+	if (!overlap) return;
+	const { cmd, via } = hostOf$1(host);
+	const command = `${cmd} publish --folder "${graph.backend.path}" --publication ${publicationId} --out <a folder outside the graph>`;
+	throw new ToolError("publish_folder_overlaps_graph", `${folder} ${OVERLAP_WORDS[overlap]} the graph "${graph.name}" (${graph.backend.path}). A publish deletes the files it did not write from the folder it publishes into, so the site needs a folder of its own outside the graph. Nothing was published. ` + (via === "cli" ? `Run: ${command}` : `Ask the user to run: ${command}`));
+}
 /** The publication page's mapping and body, through the raw handles: what `publish-service` writes to. */
 function frontmatterStore(graph) {
 	return {
@@ -17526,7 +17769,7 @@ function head(items, n = 20) {
 /**
 * Publish one publication into its Publish Folder and report. The folder is the one a person
 * set for this graph and publication on this machine (ADR 0086); a publish with Mermaid needs
-* the browser (ADR 0084).
+* the browser (ADR 0084). A dry run does everything but write, so it needs no folder.
 *
 * The result IS the report, trimmed to counts and first entries: nothing of it is written into
 * the folder, because a static host serves whatever the folder holds and the report names every
@@ -17543,10 +17786,12 @@ async function publish(graph, args, host) {
 	const publication = summary.publications.find((p) => p.id === args.id.trim());
 	if (!publication) throw publicationNotFound(args.id, summary.publications, via);
 	const folder = (await foldersFor(graph, env))(publication.id);
-	if (!folder) {
+	const dryRun = args.dryRun === true;
+	if (!folder && !dryRun) {
 		const where = graph.backend.kind === "folder" ? `--folder "${graph.backend.path}"` : `--graph "${graph.name}"`;
 		throw new ToolError("no_publish_folder", `No publish folder is set for "${publication.name}" on this machine. Ask the user to run: ${cmd} publish ${where} --publication ${publication.id} --out <dir> - that publishes once and remembers the folder for this tool.`);
 	}
+	if (folder && !dryRun) await checkPublishFolder(graph, publication.id, folder, host);
 	const selected = selectDocuments(source.documents, publication, summary.publications);
 	const includeTexts = Object.values(publication.includes).map((concept) => source.documents.find((d) => d.concept.toLowerCase() === concept.toLowerCase())?.text ?? "");
 	const bodies = [...selected.included.map((d) => d.text), ...includeTexts];
@@ -17577,7 +17822,7 @@ async function publish(graph, args, host) {
 			}),
 			unsettled
 		});
-		const written = run.report.ok ? await writeSite(nodeSiteFolder(folder), run.bundle, {
+		const written = run.report.ok && folder && !dryRun ? await writeSite(nodeSiteFolder(folder), run.bundle, {
 			seeded: run.seeded,
 			agentsMd: run.agentsMd
 		}) : null;
@@ -17585,6 +17830,7 @@ async function publish(graph, args, host) {
 		for (const e of run.report.excluded) excludedByReason[e.reason] = (excludedByReason[e.reason] ?? 0) + 1;
 		return {
 			ok: run.report.ok,
+			...dryRun ? { dryRun: true } : {},
 			publication: run.report.publication,
 			folder,
 			written: written ? {
@@ -18316,7 +18562,7 @@ function createMcpServer(source, info) {
 		"graph_insights says what the links show across the whole graph (the most-linked concepts, pages many documents ask for that do not exist yet, pages linked to nothing, groups of related concepts and the concepts bridging them), and graph_path finds how two concepts are connected. Use them to answer questions about the shape of the graph, or to suggest pages to write or link.",
 		"Start with graph_info to see what you are connected to. read_documents reads several documents in one call. tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
 		"A task reference is how a person hands you one task: its words, then an EtherPK address ending in #task=<line>-<fingerprint>. Pass the whole reference, or the address, to read_task for the task and its detail, to set_task (as reference) to change it, and to add_task_note to write what you did under it. It finds the task after lines are added above it or its tags change; if its words were edited it answers task_not_found, and you should ask the user for a fresh one.",
-		"Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. Diagrams need a browser the user installs once with \"diagrams setup\".",
+		"Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. publish with dryRun: true renders and reports without writing and needs no folder: run it after editing a publication's pages and fix what it names. Diagrams need a browser the user installs once with \"diagrams setup\".",
 		"Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
 		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document. read_asset writes an asset to a local file you can open, and list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path - name a folder relative to it, never elsewhere.",
 		"The user documentation is at https://docs.etherpk.com."
@@ -18498,7 +18744,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.")
@@ -18573,8 +18819,11 @@ function createMcpServer(source, info) {
 	}, async (args) => run((graph) => updatePublication(graph, args, host)));
 	server.registerTool("publish", {
 		title: "Publish",
-		description: "Render a publication to its publish folder on this machine and return the report: what was included and why documents were left out, missing links, assets, warnings. The folder is the one the user set with \"etherpk-mcp publish --publication <id> --out <dir>\" (error \"no_publish_folder\" until then - the tool never chooses a folder). Pages with Mermaid diagrams or maps need the browser from \"diagrams setup\" (error \"chromium_unavailable\"). The report is this result, trimmed to counts and first entries - nothing of it is written into the folder, so the site never names the documents it leaves out. Publishing writes files - it does not deploy them.",
-		inputSchema: { id: z.string().min(1) }
+		description: "Render a publication to its publish folder on this machine and return the report: what was included and why documents were left out, missing links, assets, warnings. The folder is the one the user set with \"etherpk-mcp publish --publication <id> --out <dir>\" (error \"no_publish_folder\" until then - the tool never chooses a folder), and a folder that is the graph's own folder, inside it or holding it is refused (error \"publish_folder_overlaps_graph\"). With dryRun: true it renders and reports but writes nothing and needs no folder: use it to check a publication after editing its pages, and fix what the report names. Pages with Mermaid diagrams or maps need the browser from \"diagrams setup\" (error \"chromium_unavailable\"), for a dry run too. The report is this result, trimmed to counts and first entries - nothing of it is written into the folder, so the site never names the documents it leaves out. Publishing writes files - it does not deploy them.",
+		inputSchema: {
+			id: z.string().min(1),
+			dryRun: z.boolean().optional().describe("Render and report without writing anything. No publish folder needed.")
+		}
 	}, async (args) => run((graph) => publish(graph, args, host)));
 	server.registerTool("list_themes", {
 		title: "List themes",
@@ -19010,6 +19259,7 @@ async function runGraphHost(deps) {
 				if (stopping) return answer({ etherpk: "stopping" });
 				return startSession(socket, request, reply);
 			case "publish":
+			case "publish-check":
 				if (stopping) return answer({ etherpk: "stopping" });
 				return runPublish(request, answer);
 			default: return answer({
@@ -25024,7 +25274,7 @@ function bindServeLifetime(deps) {
 *   etherpk-mcp stop   [--graph <id or name> [--sync-server <url>] | --folder <path> | --all]
 *   etherpk-mcp logout [--sync-server <url> | --all]
 *   etherpk-mcp semantic setup | status | remove
-*   etherpk-mcp publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir>]
+*   etherpk-mcp publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --dry-run]
 *   etherpk-mcp diagrams setup | status
 *
 * One config file holds a login per Sync Server (ADR 0075). `--sync-server` names the one a
@@ -25075,8 +25325,9 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       Serve a local graph folder the same way: no sign-in, no server. The agent gets search,
       backlinks, tasks and format-safe edits over the folder's markdown, alongside the files
       themselves. Edits made in an editor or by the agent directly are picked up as they land.
-      The folder must already be a graph (open it in EtherPK once) - its index is kept under
-      the cache directory, never in the folder.
+      The folder must already be a graph, with pages/ and journals/ folders in it (EtherPK
+      makes them when it opens a folder) - its index is kept under the cache directory, never
+      in the folder.
   ${CMD} running
       List the graphs served on this computer: each one's background process, its agents and
       its log. A background process stops on its own once no agent has used it for five
@@ -25095,14 +25346,18 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       to a service to be embedded.
   ${CMD} semantic status | remove
       Whether it is set up here, or delete it (logout --all deletes it too).
-  ${CMD} publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir>]
+  ${CMD} publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --dry-run]
       Publish one publication of a graph to a folder on this machine and print the report.
       --out sets the publish folder for that graph and publication and is remembered: from
       then on this command without --out, and the agent's publish tool, write to the same
-      folder (the agent cannot choose one). The folder's owned files (.html at the top,
-      assets/, theme/, the search, feed and report files) are rewritten and their strays
-      removed - everything else in it is left alone. Publishing writes files - deploying them
-      (a git push, say) is yours. Run it from cron for a site that republishes itself.
+      folder (the agent cannot choose one). It must be a folder of its own, outside the
+      graph's folder: the folder's owned files (.html at the top, assets/, theme/, the search
+      and feed files) are rewritten and their strays removed - everything else in it is left
+      alone. Publishing writes files - deploying them (a git push, say) is yours. Run it from
+      cron for a site that republishes itself.
+      --dry-run renders and checks the publication and prints the whole report, with the
+      names of the pages it mentions, but writes nothing and needs no folder. Keep its output
+      out of public logs.
   ${CMD} diagrams setup
       Let a publish draw Mermaid diagrams and maps. Downloads a Chromium (about 170 MB) into the
       cache directory with Playwright's installer, once per computer - a publish whose pages hold
@@ -25510,14 +25765,22 @@ async function publishCommand(args) {
 	const request = graphRequest("publish", args);
 	const publication = args.publication?.trim();
 	if (!publication) fail("publish needs --publication <id>. The agent's list_publications tool, or Settings → Publish in EtherPK, shows the ids.");
-	const found = await findGraph(request).catch((error) => fail(`etherpk-mcp: ${describeError(error)}`));
+	const dryRun = args["dry-run"] === true;
 	const out = args.out?.trim();
-	const { reply, socket } = await requestHost(launcherFor(found), {
+	if (dryRun && out) fail("publish --dry-run writes nothing, so it takes no --out. Leave --out off, or drop --dry-run to publish.");
+	const found = await findGraph(request).catch((error) => fail(`etherpk-mcp: ${describeError(error)}`));
+	const env = publishSettings(process.env);
+	const { reply, socket } = await requestHost(launcherFor(found), dryRun ? {
+		etherpk: "publish-check",
+		protocol: 1,
+		publication,
+		env
+	} : {
 		etherpk: "publish",
 		protocol: 1,
 		publication,
 		...out ? { out: resolve(out) } : {},
-		env: publishSettings(process.env)
+		env
 	}).catch((error) => fail(`etherpk-mcp: ${describeError(error)}`));
 	socket.destroy();
 	switch (reply.etherpk) {
@@ -25527,15 +25790,18 @@ async function publishCommand(args) {
 			process.exitCode = reply.exitCode;
 			return;
 		case "refused": return fail(reply.message);
-		case "failed": return fail(`etherpk-mcp: ${reply.message}`);
+		case "failed":
+			if (dryRun && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this computer by an older etherpk-mcp, which cannot run a dry run. Run: ${CMD} stop, then try again.`);
+			return fail(`etherpk-mcp: ${reply.message}`);
 		case "unsupported": return fail(`etherpk-mcp: this graph is served on this computer by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
 		default: return fail(`etherpk-mcp: the graph's background process gave an answer this version does not know ("${reply.etherpk}").`);
 	}
 }
 /**
 * A command-line publish, as the graph's host runs it: the publication first, so a mistyped id is
-* never remembered as a publish folder, then `--out` remembered, then the publish the agent's
-* tool runs. The answer is what the command prints, in its own words.
+* never remembered as a publish folder, then `--out` checked against the graph's folder and
+* remembered, then the publish the agent's tool runs. The answer is what the command prints, in
+* its own words.
 */
 async function publishInHost(graph, request) {
 	const env = withPublishSettings(process.env, request.env ?? {});
@@ -25546,10 +25812,23 @@ async function publishInHost(graph, request) {
 	};
 	const notes = [];
 	try {
+		if (request.etherpk === "publish-check") {
+			const result = await publish(graph, {
+				id: request.publication,
+				dryRun: true
+			}, host);
+			return {
+				etherpk: "published",
+				output: result,
+				notes: [],
+				exitCode: result.ok ? 0 : 1
+			};
+		}
 		await findPublication(graph, request.publication, host);
 		const configPath = defaultPublishFoldersPath(env);
 		const key = publishGraphKey(graph.backend, graph.graphId);
 		if (request.out) {
+			await checkPublishFolder(graph, request.publication, request.out, host);
 			await writePublishFolders(configPath, withPublishFolder(await readPublishFolders(configPath), key, request.publication, request.out));
 			notes.push(`etherpk-mcp: publish folder for "${request.publication}" of "${graph.name}" set to ${request.out} (remembered in ${configPath}).`);
 		} else if (!publishFolderOf(await readPublishFolders(configPath), key, request.publication)) return {
@@ -26072,6 +26351,7 @@ async function main() {
 			"no-semantic": { type: "boolean" },
 			publication: { type: "string" },
 			out: { type: "string" },
+			"dry-run": { type: "boolean" },
 			all: { type: "boolean" },
 			name: { type: "string" },
 			help: {