@appsoftwareltd/etherpk-mcp 0.10.0 → 0.10.2

package/README.md

@@ -38,8 +38,10 @@ No sign-in and no Sync Server:
 claude mcp add etherpk -- npx @appsoftwareltd/etherpk-mcp serve --folder /path/to/your/notes
 ```
 
-The folder must already be an EtherPK graph, so open it in EtherPK once. **Settings → Agents**
-shows this command with the path filled in once the folder's path is set on the General tab.
+The folder must already be an EtherPK graph, with `pages/` and `journals/` folders in it. EtherPK
+makes them when it opens a folder, and the [agent skill](#the-agent-skill) makes them for a new
+one. **Settings → Agents** shows this command with the path filled in once the folder's path is set
+on the General tab.
 
 ### Ask about your notes
 
@@ -169,9 +171,13 @@ npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id>
 
 - `--out` is remembered for that graph and publication. Later runs without it, and the agent's
   `publish` tool, write to the same folder.
-- The top-level `.html` files, `assets/`, `theme/` and the search, feed and report files are
-  rewritten, and files that no longer belong are removed. Everything else in the folder is left
-  alone.
+- The top-level `.html` files, `assets/`, `theme/` and the search and feed files are rewritten,
+  and files that no longer belong are removed. Everything else in the folder is left alone.
+- The folder must be one of its own, outside the graph's folder. A publish refuses the graph's
+  folder, a folder inside it and a folder that holds it, because it would remove the graph's files.
+- `--dry-run` in place of `--out` renders and checks the publication and prints the whole report,
+  with the names of the pages it mentions, without writing anything. It needs no folder. Keep its
+  output out of public logs. The agent's `publish` tool takes `dryRun: true` for the same check.
 - Deploying the folder is up to you. Run the command from cron for a site that republishes itself.
 - Mermaid diagrams and maps need a browser. A map is published as a picture of the map, drawn over
   EtherPK's map host unless `ETHERPK_MAP_STYLE_URL` names another style. `diagrams setup` installs a
@@ -180,6 +186,17 @@ npx @appsoftwareltd/etherpk-mcp publish --graph <id or name> --publication <id>
   computer instead, which NixOS needs.
 - `list_publications`, or **Settings → Publish** in EtherPK, shows the publication ids.
 
+## The agent skill
+
+The `etherpk` agent skill teaches an agent to make a blog, docs site or wiki folder in EtherPK's
+format inside any project, to check it with `publish --dry-run`, and to publish it with this
+command. For a synced graph it sends the agent to the tools above. Install it in the project the
+agent works in, or with `-g` for every project:
+
+```sh
+npx skills add appsoftwareltd/etherpk-client
+```
+
 ## Reference
 
 Every command is `npx @appsoftwareltd/etherpk-mcp <command>`. For the short form, `etherpk-mcp`,

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.10.0",
+	version: "0.10.2",
 	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",
@@ -14847,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: {
@@ -17579,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 {
@@ -17710,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
@@ -17727,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];
@@ -17761,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;
@@ -17769,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 ? {
@@ -18500,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."
@@ -18757,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",
@@ -19194,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({
@@ -25208,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
@@ -25259,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
@@ -25279,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
@@ -25694,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) {
@@ -25711,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 ?? {});
@@ -25730,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 {
@@ -26256,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: {