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

package/dist/registry.js

@@ -0,0 +1,255 @@
+import { panic } from "better-result";
+import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+import { getFolioToolDefinitions } from "@stll/folio-agents/tools";
+//#region src/registry.ts
+/**
+* The one tool vocabulary behind both surfaces. Every entry is an MCP tool
+* (its `name`, description, and envelope-wrapped input schema) and one or
+* more `folio` commands whose flags are generated from the same schema. Tools
+* that exist in `@stll/folio-agents` reuse its definitions verbatim; the file
+* envelope (`path`, `fileVersion`, ...) is added by each surface.
+*/
+const toolAccess = (tool) => {
+	switch (tool.type) {
+		case "agentRead": return "read";
+		case "agentWrite":
+		case "resolveChanges": return "write";
+		case "compare": return "readOrWrite";
+		default: return panic("Unhandled tool type", { unreachable: tool });
+	}
+};
+const agentDefinitions = new Map(getFolioToolDefinitions().map((definition) => [definition.name, definition]));
+const isJsonObjectSchema = (schema) => typeof schema === "object" && schema !== null && "type" in schema && schema.type === "object" && "properties" in schema && typeof schema.properties === "object" && schema.properties !== null && "required" in schema && Array.isArray(schema.required);
+const agentDefinition = (name) => {
+	const definition = agentDefinitions.get(name) ?? panic(`@stll/folio-agents has no tool named ${name}`);
+	const schema = definition.inputSchema;
+	if (!isJsonObjectSchema(schema)) return panic(`@stll/folio-agents tool ${name} has no object input schema`);
+	return {
+		description: definition.description,
+		schema
+	};
+};
+const agentArgsSchema = (schema, extraProperties) => ({
+	type: "object",
+	properties: {
+		...schema.properties,
+		...extraProperties
+	},
+	required: schema.required,
+	additionalProperties: false
+});
+const agentRead = ({ agentTool, commands, extraProperties = {} }) => {
+	const { description, schema } = agentDefinition(agentTool);
+	return {
+		type: "agentRead",
+		name: agentTool,
+		agentTool,
+		description,
+		argsSchema: agentArgsSchema(schema, extraProperties),
+		commands
+	};
+};
+const agentWrite = ({ agentTool, commands, editMode }) => {
+	const { description, schema } = agentDefinition(agentTool);
+	return {
+		type: "agentWrite",
+		name: agentTool,
+		agentTool,
+		editMode,
+		description,
+		argsSchema: agentArgsSchema(schema, {}),
+		commands
+	};
+};
+/** Largest page `read_document` returns on any surface. */
+const MAX_READ_BLOCKS = 1e3;
+/**
+* Paging arguments the file surface adds to `read_document`: the agents tool
+* returns the whole body, which a large contract makes too big for one reply.
+*/
+const READ_DOCUMENT_PAGING_PROPERTIES = {
+	maxBlocks: {
+		type: "integer",
+		minimum: 1,
+		maximum: MAX_READ_BLOCKS,
+		description: "Blocks per page. The response carries `nextCursor` when more remain."
+	},
+	cursor: {
+		type: "string",
+		description: "`nextCursor` from the previous page. A cursor is bound to the fileVersion it was issued for."
+	}
+};
+const RESOLVE_CHANGE_ACTIONS = ["accept", "reject"];
+const RESOLVE_CHANGES_TOOL = {
+	type: "resolveChanges",
+	name: "resolve_changes",
+	description: "Accept or reject pending tracked changes. Pass the ids from `read_changes`, or `all: true` for every change in every story; exactly one of the two. Accepting keeps an insertion and drops a deletion; rejecting does the reverse.",
+	argsSchema: {
+		type: "object",
+		properties: {
+			action: {
+				type: "string",
+				enum: RESOLVE_CHANGE_ACTIONS,
+				description: "accept or reject."
+			},
+			ids: {
+				type: "array",
+				items: { type: "string" },
+				minItems: 1,
+				description: "Change ids from read_changes."
+			},
+			all: {
+				type: "boolean",
+				description: "Resolve every pending change."
+			}
+		},
+		required: ["action"],
+		additionalProperties: false
+	},
+	commands: [{
+		name: "accept",
+		summary: "Accept tracked changes by id, or all of them",
+		preset: { action: "accept" },
+		flagNames: { ids: "id" }
+	}, {
+		name: "reject",
+		summary: "Reject tracked changes by id, or all of them",
+		preset: { action: "reject" },
+		flagNames: { ids: "id" }
+	}]
+};
+const FOLIO_FILE_TOOLS = [
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.readDocument,
+		commands: [{
+			name: "read",
+			summary: "Print the document's blocks with ids and text hashes"
+		}],
+		extraProperties: READ_DOCUMENT_PAGING_PROPERTIES
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.getDocumentOutline,
+		commands: [{
+			name: "outline",
+			summary: "Print the heading outline and section handles"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.readSection,
+		commands: [{
+			name: "section",
+			summary: "Print one section's blocks by its outline handle"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.listStories,
+		commands: [{
+			name: "stories",
+			summary: "List header, footer, and note stories"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.readStory,
+		commands: [{
+			name: "story",
+			summary: "Print one story by its handle"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.findText,
+		commands: [{
+			name: "find",
+			summary: "Find exact text and print range handles"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.readComments,
+		commands: [{
+			name: "comments",
+			summary: "Print comment threads"
+		}]
+	}),
+	agentRead({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.readChanges,
+		commands: [{
+			name: "changes",
+			summary: "Print pending tracked changes"
+		}]
+	}),
+	agentWrite({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.suggestChanges,
+		editMode: "tracked-or-direct",
+		commands: [{
+			name: "suggest",
+			summary: "Apply a batch of edit operations as tracked changes",
+			inputArrayProperty: "operations"
+		}]
+	}),
+	agentWrite({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.addComment,
+		editMode: "fixed",
+		commands: [{
+			name: "comment",
+			summary: "Comment on a block, optionally quoting text in it"
+		}]
+	}),
+	agentWrite({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.replyComment,
+		editMode: "fixed",
+		commands: [{
+			name: "reply",
+			summary: "Reply to a comment thread"
+		}]
+	}),
+	agentWrite({
+		agentTool: FOLIO_AGENT_TOOL_NAMES.resolveComment,
+		editMode: "fixed",
+		commands: [{
+			name: "resolve",
+			summary: "Resolve or reopen a comment thread"
+		}]
+	}),
+	RESOLVE_CHANGES_TOOL,
+	{
+		type: "compare",
+		name: "compare_documents",
+		description: "Compare a base `.docx` (`path`) with a revised one (`revisedPath`). Without a destination, returns the block-level differences. With one, writes the base package carrying the differences as tracked changes (a redline) there; the inputs are never modified.",
+		argsSchema: {
+			type: "object",
+			properties: {
+				revisedPath: {
+					type: "string",
+					description: "The revised .docx."
+				},
+				revisedFileVersion: {
+					type: "string",
+					description: "Refuse unless the revised file still has this SHA-256 fileVersion."
+				}
+			},
+			required: ["revisedPath"],
+			additionalProperties: false
+		},
+		commands: [{
+			name: "compare",
+			summary: "Diff two files, or write their redline with -o",
+			positionals: [{
+				name: "revised",
+				property: "revisedPath"
+			}]
+		}]
+	}
+];
+const toolsByName = new Map(FOLIO_FILE_TOOLS.map((tool) => [tool.name, tool]));
+const findFileTool = (name) => toolsByName.get(name);
+const commandsByName = /* @__PURE__ */ new Map();
+for (const tool of FOLIO_FILE_TOOLS) for (const command of tool.commands) {
+	if (commandsByName.has(command.name)) panic(`two tools declare the command ${command.name}`);
+	commandsByName.set(command.name, {
+		tool,
+		command
+	});
+}
+const findCommand = (name) => commandsByName.get(name);
+const listCommands = () => [...commandsByName.values()];
+//#endregion
+export { FOLIO_FILE_TOOLS, MAX_READ_BLOCKS, RESOLVE_CHANGE_ACTIONS, findCommand, findFileTool, listCommands, toolAccess };

package/dist/render.d.ts

@@ -0,0 +1,35 @@
+import { FolioCliError } from "./errors.js";
+import { LoadedFile } from "./document.js";
+import { Result } from "better-result";
+import { DisplayList } from "@stll/folio-core/display-list/types";
+import { FontsourceFaces } from "@stll/folio-core/fonts/fontsourceFaces";
+//#region src/render.d.ts
+declare const RENDER_FORMATS: readonly ["pdf", "png", "html"];
+type RenderFormat = (typeof RENDER_FORMATS)[number];
+/** The CLI's `@fontsource` faces, shared by every render in the process. */
+declare const cliFontFaces: () => FontsourceFaces;
+/** The document's display list, measured with the CLI's faces. */
+declare const buildDisplayList: (file: LoadedFile) => Promise<Result<DisplayList, FolioCliError>>;
+/** Refuse page numbers the document does not have; `undefined` keeps every page. */
+declare const checkPages: (list: DisplayList, pages: readonly number[] | undefined) => Result<DisplayList, FolioCliError>;
+/** Standalone HTML for the list, with its faces inlined. */
+declare const displayListHtml: (list: DisplayList, title: string) => string;
+type RenderPdfOptions = {
+  file: LoadedFile;
+  pages: readonly number[] | undefined;
+  timestamp: string;
+};
+type RenderedOutput = {
+  bytes: Uint8Array;
+  pageCount: number;
+};
+declare const renderPdf: ({ file, pages, timestamp }: RenderPdfOptions) => Promise<Result<RenderedOutput, FolioCliError>>;
+type RenderPngOptions = {
+  file: LoadedFile;
+  page: number;
+  scale: number;
+};
+/** One page as a PNG: the DOM backend's page, screenshotted in headless Chromium. */
+declare const renderPng: ({ file, page, scale }: RenderPngOptions) => Promise<Result<RenderedOutput, FolioCliError>>;
+//#endregion
+export { RENDER_FORMATS, RenderFormat, RenderedOutput, buildDisplayList, checkPages, cliFontFaces, displayListHtml, renderPdf, renderPng };

package/dist/render.js

@@ -0,0 +1,120 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { createRequire } from "node:module";
+import { Result } from "better-result";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { selectDisplayPages } from "@stll/folio-core/display-list/selectDisplayPages";
+import { renderDisplayListToHtml } from "@stll/folio-core/display-list/html/renderDisplayListToHtml";
+import { buildDocxDisplayList, writeDisplayListPdf } from "@stll/folio-core/export-pdf";
+import { createFontsourceFaces } from "@stll/folio-core/fonts/fontsourceFaces";
+//#region src/render.ts
+/**
+* Render a document with folio's own layout and painters, headlessly: PDF
+* from the PDF backend, HTML from the DOM backend, and PNG by screenshotting
+* that HTML in Chromium. Every format paints the one display list built from
+* one layout, measured with the `@fontsource` faces the CLI installs.
+*
+* PNG needs a browser. `playwright-core` is an optional peer dependency and
+* is imported only when a PNG is asked for.
+*/
+const RENDER_FORMATS = [
+	"pdf",
+	"png",
+	"html"
+];
+const requireFromHere = createRequire(import.meta.url);
+/** The installed `@fontsource/<name>` directory, or `null` when it is not installed. */
+const fontsourceDirectory = (packageName) => {
+	const resolved = Result.try(() => requireFromHere.resolve(`@fontsource/${packageName}/package.json`));
+	return resolved.isOk() ? path.dirname(resolved.value) : null;
+};
+let faces;
+/** The CLI's `@fontsource` faces, shared by every render in the process. */
+const cliFontFaces = () => {
+	faces ??= createFontsourceFaces({ read: (packageName, relativePath) => {
+		const directory = fontsourceDirectory(packageName);
+		if (directory === null) return null;
+		const filePath = path.join(directory, relativePath);
+		return existsSync(filePath) ? new Uint8Array(readFileSync(filePath)) : null;
+	} });
+	return faces;
+};
+const renderError = (message) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+	message
+});
+const describe = (error) => error instanceof Error ? error.message : String(error);
+/** The document's display list, measured with the CLI's faces. */
+const buildDisplayList = async (file) => {
+	const built = await buildDocxDisplayList(file.bytes.slice().buffer, { fonts: cliFontFaces().source });
+	return built.isOk() ? Result.ok(built.value.list) : Result.err(renderError(`${file.path} could not be laid out: ${built.error.message}`));
+};
+/** Refuse page numbers the document does not have; `undefined` keeps every page. */
+const checkPages = (list, pages) => {
+	if (pages === void 0) return Result.ok(list);
+	const missing = pages.filter((page) => !Number.isInteger(page) || page < 1 || page > list.pages.length);
+	if (missing.length > 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidInput,
+		message: `The document has ${list.pages.length} page${list.pages.length === 1 ? "" : "s"}; no page ${missing.join(", ")}.`
+	}));
+	return Result.ok(selectDisplayPages(list, pages.map((page) => page - 1)));
+};
+/** Standalone HTML for the list, with its faces inlined. */
+const displayListHtml = (list, title) => renderDisplayListToHtml(list, {
+	title,
+	fontFaceCss: cliFontFaces().fontFaceCss({ families: list.fonts.map((face) => face.family) }),
+	pageGapPx: 16,
+	canvasColor: "#e8e8e8"
+});
+const renderPdf = async ({ file, pages, timestamp }) => {
+	const list = await buildDisplayList(file);
+	if (list.isErr()) return Result.err(list.error);
+	const selected = checkPages(list.value, pages);
+	if (selected.isErr()) return Result.err(selected.error);
+	const exported = await writeDisplayListPdf(selected.value, {
+		fonts: cliFontFaces().source,
+		timestamp,
+		producer: "folio"
+	});
+	return exported.isOk() ? Result.ok({
+		bytes: exported.value.bytes,
+		pageCount: exported.value.pageCount
+	}) : Result.err(renderError(`${file.path} could not be exported: ${exported.error.message}`));
+};
+const hasChromium = (module) => typeof module === "object" && module !== null && "chromium" in module && typeof module.chromium === "object" && module.chromium !== null && "launch" in module.chromium;
+const rasterUnavailable = (detail) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.rendererUnavailable,
+	message: `PNG rendering needs Chromium through playwright-core: ${detail}`,
+	hint: "Install it next to the CLI (npm install playwright-core) and its browser (npx playwright-core install chromium), or render a PDF."
+});
+/** One page as a PNG: the DOM backend's page, screenshotted in headless Chromium. */
+const renderPng = async ({ file, page, scale }) => {
+	const list = await buildDisplayList(file);
+	if (list.isErr()) return Result.err(list.error);
+	const selected = checkPages(list.value, [page]);
+	if (selected.isErr()) return Result.err(selected.error);
+	const imported = await Result.tryPromise(() => import("playwright-core"));
+	if (imported.isErr()) return Result.err(rasterUnavailable("the package is not installed"));
+	const module = imported.value;
+	if (!hasChromium(module)) return Result.err(rasterUnavailable("the package has no chromium"));
+	const shot = await Result.tryPromise({
+		try: async () => {
+			const browser = await module.chromium.launch({ headless: true });
+			try {
+				const tab = await browser.newPage({ deviceScaleFactor: scale });
+				await tab.setContent(displayListHtml(selected.value, path.basename(file.path)), { waitUntil: "load" });
+				await tab.evaluate("document.fonts.ready");
+				return await tab.locator(".layout-page").first().screenshot({ type: "png" });
+			} finally {
+				await browser.close();
+			}
+		},
+		catch: (error) => rasterUnavailable(describe(error))
+	});
+	return shot.isOk() ? Result.ok({
+		bytes: shot.value,
+		pageCount: 1
+	}) : Result.err(shot.error);
+};
+//#endregion
+export { RENDER_FORMATS, buildDisplayList, checkPages, cliFontFaces, displayListHtml, renderPdf, renderPng };

package/dist/roots.d.ts

@@ -0,0 +1,21 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+//#region src/roots.d.ts
+/** Real paths of the allowed root directories. */
+type AllowedRoots = readonly string[];
+/** Resolve each root to its real path; every root must be an existing directory. */
+declare const resolveRoots: (roots: readonly string[]) => Promise<Result<AllowedRoots, FolioCliError>>;
+type CheckWithinRootsOptions = {
+  roots: AllowedRoots;
+  /** As the caller passed it; a relative path resolves against the first root. */
+  target: string;
+  /** Which argument named the path, for the refusal message. */
+  argument: string;
+};
+/**
+ * Refuse a path outside every allowed root, returning the resolved path the
+ * call should use.
+ */
+declare const checkWithinRoots: ({ roots, target, argument }: CheckWithinRootsOptions) => Promise<Result<string, FolioCliError>>;
+//#endregion
+export { AllowedRoots, checkWithinRoots, resolveRoots };

package/dist/roots.js

@@ -0,0 +1,57 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/roots.ts
+/**
+* Allowed roots for the MCP server: every path a tool call reads or writes
+* must resolve, through symlinks, inside one of them. A destination that does
+* not exist yet is checked through its parent directory.
+*
+* The check resolves a path once; the write path re-checks what it opens
+* (device and inode) and the directory's real path before its rename. A
+* local process renaming directories under a root while a call runs can
+* still race the check; the package README lists this as a known limit.
+*/
+/** Resolve each root to its real path; every root must be an existing directory. */
+const resolveRoots = async (roots) => {
+	const resolved = [];
+	for (const root of roots) {
+		const real = await Result.tryPromise(() => realpath(path.resolve(root)));
+		const info = real.isOk() ? await Result.tryPromise(() => stat(real.value)) : null;
+		if (!real.isOk() || info === null || !info.isOk() || !info.value.isDirectory()) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.usage,
+			message: `--root ${root} is not an existing directory.`
+		}));
+		resolved.push(real.value);
+	}
+	return Result.ok(resolved);
+};
+const isWithin = (root, candidate) => {
+	const relative = path.relative(root, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+/** The real path of `target`, or of its parent joined with its name when it does not exist. */
+const realTarget = async (target) => {
+	const real = await Result.tryPromise(() => realpath(target));
+	if (real.isOk()) return real.value;
+	const parent = await Result.tryPromise(() => realpath(path.dirname(target)));
+	return parent.isOk() ? path.join(parent.value, path.basename(target)) : null;
+};
+/**
+* Refuse a path outside every allowed root, returning the resolved path the
+* call should use.
+*/
+const checkWithinRoots = async ({ roots, target, argument }) => {
+	const base = roots.at(0) ?? process.cwd();
+	const absolute = path.resolve(base, target);
+	const real = await realTarget(absolute);
+	if (real !== null && roots.some((root) => isWithin(root, real))) return Result.ok(real);
+	return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.outsideRoot,
+		message: `${argument} ${JSON.stringify(target)} is outside the allowed roots.`,
+		hint: `Use a path under ${roots.join(", ")}, or restart the server with another --root.`
+	}));
+};
+//#endregion
+export { checkWithinRoots, resolveRoots };

package/dist/serve.d.ts

@@ -0,0 +1,17 @@
+import { Result } from "better-result";
+//#region src/serve.d.ts
+declare const PREVIEW_HOST = "127.0.0.1";
+type PreviewServerOptions = {
+  documentPath: string;
+  /** 0 picks a free port. */
+  port: number;
+};
+type PreviewServer = {
+  /** The preview URL, token included. */
+  url: string;
+  close: () => Promise<void>;
+};
+/** Serve the preview until {@link PreviewServer.close}. */
+declare const startPreviewServer: ({ documentPath, port }: PreviewServerOptions) => Promise<Result<PreviewServer, Error>>;
+//#endregion
+export { PREVIEW_HOST, PreviewServer, PreviewServerOptions, startPreviewServer };