@stll/folio-cli 0.0.1-placeholder.0 → 0.1.1

package/dist/mcp.js

@@ -0,0 +1,310 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { executeReadTool } from "./execute-read.js";
+import { executeWriteTool } from "./execute-write.js";
+import { failureEnvelope, successEnvelope } from "./output.js";
+import { version } from "./package.js";
+import { FOLIO_FILE_TOOLS, findFileTool, toolAccess } from "./registry.js";
+import { checkWithinRoots } from "./roots.js";
+import { Result, panic } from "better-result";
+import { FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA } from "@stll/folio-agents/operation-schema";
+import { ProtocolError, ProtocolErrorCode, Server } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+//#region src/mcp.ts
+/**
+* `folio mcp`: the file tool registry as a Model Context Protocol server over
+* stdio. The protocol owns stdout; diagnostics go to stderr. Every tool takes
+* the file envelope (`path`, `fileVersion`, and for writes `destination`,
+* `txId`, ...) beside its own arguments, every path must resolve inside an
+* allowed root, and results are the same `{ ok, data | error }` envelope the
+* command line prints.
+*/
+/** Limits on what one MCP tool call returns. */
+const MCP_READ_BOUNDS = {
+	defaultMaxBlocks: 200,
+	maxMatches: 100,
+	maxResponseBytes: 256 * 1024
+};
+const ABOUT_URI = "folio://about";
+const OPERATIONS_SCHEMA_URI = "folio://schema/operations";
+const INSTRUCTIONS = "Tools read and change .docx files on disk. Start with get_document_outline or read_document to get block ids and the file's fileVersion; find_text returns exact range handles. Mutating tools require the fileVersion you read and refuse (stale_version) when the file changed; re-read and retry. Edits are tracked changes unless mode is direct. Without destination a change is written in place with a backup; with destination it goes to that new file. Results are { ok, data } or { ok: false, error: { code, message, hint } }.";
+const PATH_PROPERTY = {
+	type: "string",
+	description: "The .docx file, absolute or relative to the first allowed root."
+};
+const envelopeProperties = (tool) => {
+	const access = toolAccess(tool);
+	const properties = {
+		path: PATH_PROPERTY,
+		fileVersion: {
+			type: "string",
+			pattern: "^[0-9a-f]{64}$",
+			description: {
+				write: "The file's fileVersion (SHA-256) from your latest read. Required: a change to a file that moved on is refused.",
+				readOrWrite: "The file's fileVersion (SHA-256) from your latest read; required with `destination`.",
+				read: "When given, refuse unless the file still has this fileVersion."
+			}[access]
+		}
+	};
+	if (access === "read") return properties;
+	Object.assign(properties, {
+		destination: {
+			type: "string",
+			description: access === "write" ? "Write the result to this .docx instead of changing `path` in place. It must not start with a dot or sit inside .folio." : "Write the redline to this .docx. Without it, only the differences are returned."
+		},
+		overwrite: {
+			type: "boolean",
+			description: "Let `destination` replace an existing .docx; needs `expectedDestinationVersion`. The replaced file is backed up."
+		},
+		expectedDestinationVersion: {
+			type: "string",
+			pattern: "^[0-9a-f]{64}$",
+			description: "The fileVersion of the existing file `destination` replaces."
+		},
+		txId: {
+			type: "string",
+			pattern: "^[\\w.-]{1,128}$",
+			description: "Idempotency key: repeating a committed call returns its original receipt."
+		}
+	});
+	if (access === "write") Object.assign(properties, { allowRepack: {
+		type: "boolean",
+		description: "Allow rewriting the whole package when the change cannot be patched in (e.g. paragraphs added or removed)."
+	} });
+	if (tool.type === "agentWrite" && tool.editMode === "tracked-or-direct") Object.assign(properties, { mode: {
+		type: "string",
+		enum: ["tracked", "direct"],
+		description: "tracked (default) records tracked changes; direct edits the text."
+	} });
+	return properties;
+};
+/** The tool's MCP input schema: its own arguments plus the file envelope. */
+const mcpInputSchema = (tool) => {
+	const envelope = envelopeProperties(tool);
+	for (const key of Object.keys(envelope)) if (key in tool.argsSchema.properties) panic(`${tool.name} declares ${key}, which the file envelope also uses`);
+	const access = toolAccess(tool);
+	return {
+		type: "object",
+		properties: {
+			...envelope,
+			...tool.argsSchema.properties
+		},
+		required: [
+			"path",
+			...access === "write" ? ["fileVersion"] : [],
+			...tool.argsSchema.required
+		],
+		additionalProperties: false
+	};
+};
+const isJsonValue = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	return typeof value === "object" && Object.values(value).every(isJsonValue);
+};
+/** The registry schemas are JSON by construction; a value that is not is a registry bug. */
+const toJsonObject = (properties) => {
+	const object = {};
+	for (const [key, value] of Object.entries(properties)) object[key] = isJsonValue(value) ? value : panic(`Schema property ${key} is not JSON`);
+	return object;
+};
+const toMcpInputSchema = ({ properties, required }) => ({
+	type: "object",
+	properties: toJsonObject(properties),
+	required: [...required],
+	additionalProperties: false
+});
+const listMcpTools = () => FOLIO_FILE_TOOLS.map((tool) => ({
+	name: tool.name,
+	description: tool.description,
+	inputSchema: toMcpInputSchema(mcpInputSchema(tool)),
+	annotations: {
+		readOnlyHint: toolAccess(tool) === "read",
+		destructiveHint: toolAccess(tool) !== "read",
+		openWorldHint: false
+	}
+}));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidInput = (message) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message
+});
+const ENVELOPE_KEYS = /* @__PURE__ */ new Set([
+	"path",
+	"fileVersion",
+	"destination",
+	"overwrite",
+	"expectedDestinationVersion",
+	"txId",
+	"allowRepack",
+	"mode"
+]);
+const optionalString = (value, name) => value === void 0 || typeof value === "string" ? Result.ok(value) : Result.err(invalidInput(`${name} must be a string.`));
+const toRevisionDate = (date) => date.toISOString().replace(/\.\d{3}Z$/u, "Z");
+const runTool = async (tool, rawArgs, context) => {
+	if (rawArgs !== void 0 && !isRecord(rawArgs)) return Result.err(invalidInput("Tool arguments must be an object."));
+	const input = rawArgs ?? {};
+	const args = {};
+	for (const [key, value] of Object.entries(input)) if (!ENVELOPE_KEYS.has(key)) args[key] = value;
+	const rawPath = input["path"];
+	if (typeof rawPath !== "string" || rawPath === "") return Result.err(invalidInput("path is required."));
+	const filePath = await checkWithinRoots({
+		roots: context.roots,
+		target: rawPath,
+		argument: "path"
+	});
+	if (filePath.isErr()) return filePath;
+	const fileVersion = optionalString(input["fileVersion"], "fileVersion");
+	if (fileVersion.isErr()) return fileVersion;
+	const destination = optionalString(input["destination"], "destination");
+	if (destination.isErr()) return destination;
+	const txId = optionalString(input["txId"], "txId");
+	if (txId.isErr()) return txId;
+	if (tool.type === "compare") {
+		const revised = args["revisedPath"];
+		if (typeof revised !== "string") return Result.err(invalidInput("revisedPath is required."));
+		const revisedPath = await checkWithinRoots({
+			roots: context.roots,
+			target: revised,
+			argument: "revisedPath"
+		});
+		if (revisedPath.isErr()) return revisedPath;
+		args["revisedPath"] = revisedPath.value;
+	}
+	const call = {
+		path: filePath.value,
+		fileVersion: fileVersion.value,
+		args
+	};
+	const access = toolAccess(tool);
+	if (access === "read" || access === "readOrWrite" && destination.value === void 0) return await executeReadTool(tool, call, context.bounds);
+	if (context.author === void 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.authorRequired,
+		message: "This server has no author configured for changes.",
+		hint: "Restart folio mcp with --author, FOLIO_AUTHOR, or a git user.name."
+	}));
+	const expectedDestinationVersion = optionalString(input["expectedDestinationVersion"], "expectedDestinationVersion");
+	if (expectedDestinationVersion.isErr()) return expectedDestinationVersion;
+	let target = { type: "inPlace" };
+	if (destination.value !== void 0) {
+		const checked = await checkWithinRoots({
+			roots: context.roots,
+			target: destination.value,
+			argument: "destination"
+		});
+		if (checked.isErr()) return checked;
+		target = {
+			type: "file",
+			path: checked.value,
+			overwrite: input["overwrite"] === true,
+			expectedVersion: expectedDestinationVersion.value
+		};
+	}
+	return await executeWriteTool(tool, call, {
+		sourcePrecondition: "required",
+		destination: target,
+		author: context.author,
+		date: toRevisionDate(context.now()),
+		repack: input["allowRepack"] === true ? "allow" : "refuse",
+		force: false,
+		txId: txId.value,
+		journalPath: void 0,
+		mode: input["mode"] === "direct" ? "direct" : "tracked-changes"
+	});
+};
+const toCallToolResult = (result) => {
+	const envelope = result.isOk() ? successEnvelope(result.value) : failureEnvelope(result.error);
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(envelope)
+		}],
+		isError: !envelope.ok
+	};
+};
+const aboutText = (roots) => [
+	`# folio ${version}`,
+	"",
+	`Allowed roots: ${roots.join(", ")}`,
+	"",
+	"- fileVersion is the SHA-256 of the file's bytes; changes require the one you read.",
+	"- Block ids are the paragraph's w14:paraId (blockIdSource: package) or derived from text and",
+	"  position (synthetic), valid only for the fileVersion they were read at.",
+	"- Offsets in range handles are UTF-16 code units into the block text read_document returns.",
+	"- A change writes atomically in place or to destination (a plain .docx, never a dotfile or inside",
+	"  .folio); replacing an existing file needs overwrite plus expectedDestinationVersion. Whatever is",
+	"  replaced is backed up in .folio/backups/<name>/. Changes are journaled in .folio/journal.jsonl and",
+	"  refuse a full package repack unless allowRepack is true.",
+	"- A batch lands whole or not at all: stale_target, ambiguous_target, and other refusals write nothing.",
+	""
+].join("\n");
+const readResource = (uri, roots) => {
+	if (uri === ABOUT_URI) return { contents: [{
+		uri,
+		mimeType: "text/markdown",
+		text: aboutText(roots)
+	}] };
+	if (uri === OPERATIONS_SCHEMA_URI) return { contents: [{
+		uri,
+		mimeType: "application/schema+json",
+		text: JSON.stringify(FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA)
+	}] };
+	return null;
+};
+/** A low-level MCP server exposing the file tools; connect it to a transport. */
+const createFolioMcpServer = (options) => {
+	const context = {
+		...options,
+		bounds: options.bounds ?? MCP_READ_BOUNDS,
+		now: options.now ?? (() => /* @__PURE__ */ new Date())
+	};
+	const server = new Server({
+		name: "folio",
+		version
+	}, {
+		capabilities: {
+			tools: {},
+			resources: {}
+		},
+		instructions: INSTRUCTIONS
+	});
+	server.setRequestHandler("tools/list", () => ({ tools: listMcpTools() }));
+	server.setRequestHandler("tools/call", async (request) => {
+		const tool = findFileTool(request.params.name);
+		if (tool === void 0) return toCallToolResult(Result.err(invalidInput(`Unknown tool ${JSON.stringify(request.params.name)}.`)));
+		const result = await Result.tryPromise({
+			try: () => runTool(tool, request.params.arguments, context),
+			catch: (error) => cliError({
+				code: FOLIO_CLI_ERROR_CODES.internal,
+				message: error instanceof Error ? error.message : String(error)
+			})
+		});
+		return toCallToolResult(result.isOk() ? result.value : result);
+	});
+	server.setRequestHandler("resources/list", () => ({ resources: [{
+		uri: ABOUT_URI,
+		name: "about",
+		mimeType: "text/markdown"
+	}, {
+		uri: OPERATIONS_SCHEMA_URI,
+		name: "operations-schema",
+		mimeType: "application/schema+json"
+	}] }));
+	server.setRequestHandler("resources/read", (request) => {
+		const resource = readResource(request.params.uri, context.roots);
+		if (resource === null) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown resource: ${request.params.uri}`);
+		return resource;
+	});
+	return server;
+};
+/** Serve the file tools over stdio until the client disconnects. */
+const serveFolioMcp = async ({ input, output, ...options }) => {
+	const server = createFolioMcpServer(options);
+	const closed = new Promise((resolve) => {
+		server.onclose = () => resolve();
+	});
+	await server.connect(new StdioServerTransport(input, output));
+	await closed;
+};
+//#endregion
+export { MCP_READ_BOUNDS, createFolioMcpServer, listMcpTools, mcpInputSchema, serveFolioMcp };

package/dist/output-file.d.ts

@@ -0,0 +1,14 @@
+import { FolioCliError } from "./errors.js";
+import { FileIdentity } from "./document.js";
+import { Result } from "better-result";
+//#region src/output-file.d.ts
+type WriteOutputOptions = {
+  target: string;
+  bytes: Uint8Array;
+  overwrite: boolean;
+  /** The document rendered, which the output must not replace. */
+  input: FileIdentity;
+};
+declare const writeOutputFile: ({ target, bytes, overwrite, input }: WriteOutputOptions) => Promise<Result<string, FolioCliError>>;
+//#endregion
+export { writeOutputFile };

package/dist/output-file.js

@@ -0,0 +1,60 @@
+import { NO_FOLLOW, errnoCode, sameFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/output-file.ts
+/**
+* Write a rendered file (PDF, PNG, HTML) next to where the caller asked: to a
+* temporary name in the same directory, flushed, then renamed into place, so
+* a reader never sees half a file. An existing file is replaced only with
+* `overwrite`, and never when it is the input document.
+*/
+const fileSystemError = (message, error) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${message}: ${error instanceof Error ? error.message : String(error)}`
+});
+const writeOutputFile = async ({ target, bytes, overwrite, input }) => {
+	const absolute = path.resolve(target);
+	const directory = await Result.tryPromise(() => realpath(path.dirname(absolute)));
+	if (directory.isErr()) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.notFound,
+		message: `No directory ${path.dirname(absolute)}.`
+	}));
+	const destination = path.join(directory.value, path.basename(absolute));
+	const existing = await Result.tryPromise(() => stat(destination));
+	if (existing.isOk()) {
+		if (sameFile({
+			dev: existing.value.dev,
+			ino: existing.value.ino
+		}, input)) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.invalidDestination,
+			message: `${destination} is the document being rendered.`
+		}));
+		if (!overwrite) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.destinationExists,
+			message: `${destination} already exists.`,
+			hint: "Pass --overwrite to replace it."
+		}));
+	} else if (errnoCode(existing.error.cause) !== "ENOENT") return Result.err(fileSystemError(`Cannot inspect ${destination}`, existing.error.cause));
+	const temporary = path.join(directory.value, `.${path.basename(absolute)}.${randomUUID()}.tmp`);
+	const written = await Result.tryPromise(async () => {
+		const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NO_FOLLOW, 420);
+		try {
+			await handle.writeFile(bytes);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await rename(temporary, destination);
+	});
+	if (written.isErr()) {
+		await rm(temporary, { force: true });
+		return Result.err(fileSystemError(`Cannot write ${destination}`, written.error.cause));
+	}
+	return Result.ok(destination);
+};
+//#endregion
+export { writeOutputFile };

package/dist/output.d.ts

@@ -0,0 +1,33 @@
+import { FolioCliError, FolioCliErrorCode } from "./errors.js";
+//#region src/output.d.ts
+declare const OUTPUT_FORMATS: readonly ["json", "text"];
+type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+declare const isOutputFormat: (value: unknown) => value is OutputFormat;
+type FailureBody = {
+  code: FolioCliErrorCode;
+  message: string;
+  hint?: string;
+  details?: unknown;
+};
+type Envelope = {
+  ok: true;
+  data: unknown;
+} | {
+  ok: false;
+  error: FailureBody;
+};
+declare const successEnvelope: (data: unknown) => Envelope;
+declare const failureEnvelope: ({ code, message, hint, details }: FolioCliError) => Envelope;
+type RenderedOutput = {
+  stdout: string;
+  stderr: string;
+};
+type RenderEnvelopeOptions = {
+  envelope: Envelope;
+  format: OutputFormat;
+  /** The tool that produced the data, for its text rendering. */
+  tool: string;
+};
+declare const renderEnvelope: ({ envelope, format, tool }: RenderEnvelopeOptions) => RenderedOutput;
+//#endregion
+export { Envelope, FailureBody, OUTPUT_FORMATS, OutputFormat, RenderedOutput, failureEnvelope, isOutputFormat, renderEnvelope, successEnvelope };

package/dist/output.js

@@ -0,0 +1,77 @@
+//#region src/output.ts
+const OUTPUT_FORMATS = ["json", "text"];
+const isOutputFormat = (value) => OUTPUT_FORMATS.some((format) => format === value);
+const successEnvelope = (data) => ({
+	ok: true,
+	data
+});
+const failureEnvelope = ({ code, message, hint, details }) => ({
+	ok: false,
+	error: {
+		code,
+		message,
+		...hint !== void 0 && { hint },
+		...details !== void 0 && { details }
+	}
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => typeof value === "string" ? value : "";
+const renderBlocks = (blocks) => blocks.filter(isRecord).map((block) => `[${text(block["blockId"])}] ${text(block["text"])}`);
+const renderComments = (comments) => {
+	const lines = [];
+	for (const comment of comments.filter(isRecord)) {
+		const status = comment["resolved"] === true ? " (resolved)" : "";
+		lines.push(`#${text(comment["id"])} ${text(comment["author"])}${status}: ${text(comment["text"])}`);
+		const replies = Array.isArray(comment["replies"]) ? comment["replies"] : [];
+		for (const reply of replies.filter(isRecord)) lines.push(`  #${text(reply["id"])} ${text(reply["author"])}: ${text(reply["text"])}`);
+	}
+	return lines;
+};
+const renderChanges = (changes) => changes.filter(isRecord).map((change) => `#${String(change["id"])} ${text(change["type"])} by ${text(change["author"])}: ${text(change["text"])}`);
+const renderMatches = (matches) => matches.filter(isRecord).map((match) => `[${text(match["blockId"]) || "story"}] ${text(match["context"])}`);
+/** Readable lines for a tool result, or `null` to fall back to pretty JSON. */
+const renderResult = (tool, result) => {
+	if (tool === "read_document" && isRecord(result) && Array.isArray(result["blocks"])) {
+		const lines = renderBlocks(result["blocks"]);
+		if (typeof result["nextCursor"] === "string") lines.push(`(more: --cursor ${result["nextCursor"]})`);
+		return lines;
+	}
+	if (tool === "read_section" && isRecord(result) && Array.isArray(result["blocks"])) return renderBlocks(result["blocks"]);
+	if (tool === "find_text" && isRecord(result) && Array.isArray(result["matches"])) return [...renderMatches(result["matches"]), `(${String(result["totalMatches"])} matches)`];
+	if (tool === "read_comments" && Array.isArray(result)) return renderComments(result);
+	if (tool === "read_changes" && Array.isArray(result)) return renderChanges(result);
+	if (tool === "compare_documents" && isRecord(result) && typeof result["text"] === "string") return [result["text"]];
+	return null;
+};
+const shortVersion = (value) => text(value).slice(0, 12);
+/** One line per committed or replayed transaction. */
+const renderReceipt = (receipt) => {
+	const parts = Array.isArray(receipt["changedParts"]) ? receipt["changedParts"].length : 0;
+	const backup = typeof receipt["backup"] === "string" ? `\nbackup: ${receipt["backup"]}` : "";
+	return `${text(receipt["status"])} ${text(receipt["txId"])}: ${text(receipt["path"])} ${shortVersion(receipt["fromVersion"])} -> ${shortVersion(receipt["fileVersion"])} (${text(receipt["saveStrategy"])}, ${parts} part${parts === 1 ? "" : "s"} changed)${backup}\n`;
+};
+const renderData = (tool, data) => {
+	if (!isRecord(data)) return `${JSON.stringify(data, null, 2)}\n`;
+	if (typeof data["txId"] === "string" && typeof data["status"] === "string") return renderReceipt(data);
+	const header = typeof data["path"] === "string" && typeof data["fileVersion"] === "string" ? [`${data["path"]} @ ${data["fileVersion"]}`] : [];
+	const lines = renderResult(tool, data["result"]);
+	if (lines === null) return `${JSON.stringify(data, null, 2)}\n`;
+	return `${[...header, ...lines].join("\n")}\n`;
+};
+const renderEnvelope = ({ envelope, format, tool }) => {
+	if (format === "json") return {
+		stdout: `${JSON.stringify(envelope)}\n`,
+		stderr: ""
+	};
+	if (envelope.ok) return {
+		stdout: renderData(tool, envelope.data),
+		stderr: ""
+	};
+	const hint = envelope.error.hint === void 0 ? "" : `hint: ${envelope.error.hint}\n`;
+	return {
+		stdout: "",
+		stderr: `error: ${envelope.error.message}\n${hint}`
+	};
+};
+//#endregion
+export { OUTPUT_FORMATS, failureEnvelope, isOutputFormat, renderEnvelope, successEnvelope };

package/dist/package-parts.d.ts

@@ -0,0 +1,24 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+//#region src/package-parts.d.ts
+type PartChange = "added" | "modified" | "removed";
+type ChangedPart = {
+  part: string;
+  change: PartChange;
+};
+/** Parts added, removed, or whose uncompressed content differs, sorted by name. */
+declare const diffPackages: (before: Uint8Array, after: Uint8Array) => Promise<Result<ChangedPart[], FolioCliError>>;
+/**
+ * The first revision id above every WordprocessingML `id` attribute in the
+ * package, so new revisions never collide with an existing one.
+ */
+declare const nextRevisionIdSeed: (bytes: Uint8Array) => Promise<Result<number, FolioCliError>>;
+/**
+ * Check what a save wrote before it replaces anything: the package opens,
+ * every changed XML part is well formed, every relationship id a changed
+ * part references resolves, every internal target a changed `.rels` part
+ * names exists, and the package parses as a document again.
+ */
+declare const checkPackageIntegrity: (bytes: Uint8Array<ArrayBuffer>, changedParts: readonly ChangedPart[]) => Promise<Result<void, FolioCliError>>;
+//#endregion
+export { ChangedPart, PartChange, checkPackageIntegrity, diffPackages, nextRevisionIdSeed };