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

package/dist/errors.js

@@ -0,0 +1,92 @@
+import { TaggedError, panic } from "better-result";
+//#region src/errors.ts
+/**
+* Process exit classes. The numbers match the stella command line's table so
+* a script driving both branches on one set of codes; folio uses the subset a
+* local file tool can produce.
+*/
+const EXIT_CODES = {
+	ok: 0,
+	unexpected: 1,
+	validation: 2,
+	notFound: 6,
+	permissionDenied: 8,
+	conflict: 10
+};
+const EXIT_CODE_DESCRIPTIONS = {
+	ok: "success",
+	unexpected: "unexpected internal error",
+	validation: "usage, input, or refused-operation error",
+	notFound: "file, change, or comment not found",
+	permissionDenied: "path outside the allowed roots, or unsafe to write through",
+	conflict: "conflict with current state (stale version, lock held, destination exists)"
+};
+/** Every exit code with its meaning, ordered numerically, for `--help`. */
+const exitCodeEntries = () => {
+	const descriptions = EXIT_CODE_DESCRIPTIONS;
+	return Object.entries(EXIT_CODES).toSorted(([, left], [, right]) => left - right).map(([key, code]) => ({
+		code,
+		meaning: descriptions[key] ?? panic(`exit code ${key} has no description`)
+	}));
+};
+/** Machine codes carried in `error.code` of a failure envelope. */
+const FOLIO_CLI_ERROR_CODES = {
+	usage: "usage_error",
+	invalidInput: "invalid_input",
+	invalidDocument: "invalid_document",
+	tooLarge: "too_large",
+	notFound: "not_found",
+	outsideRoot: "outside_root",
+	unsafePath: "unsafe_path",
+	invalidDestination: "invalid_destination",
+	staleVersion: "stale_version",
+	staleTarget: "stale_target",
+	ambiguousTarget: "ambiguous_target",
+	operationRejected: "operation_rejected",
+	repackRequired: "repack_required",
+	authorRequired: "author_required",
+	locked: "locked",
+	destinationExists: "destination_exists",
+	transactionConflict: "transaction_conflict",
+	integrityFailed: "integrity_failed",
+	rendererUnavailable: "renderer_unavailable",
+	internal: "internal_error"
+};
+const ERROR_CODE_EXIT = {
+	usage_error: EXIT_CODES.validation,
+	invalid_input: EXIT_CODES.validation,
+	invalid_document: EXIT_CODES.validation,
+	too_large: EXIT_CODES.validation,
+	not_found: EXIT_CODES.notFound,
+	outside_root: EXIT_CODES.permissionDenied,
+	unsafe_path: EXIT_CODES.permissionDenied,
+	invalid_destination: EXIT_CODES.validation,
+	stale_version: EXIT_CODES.conflict,
+	stale_target: EXIT_CODES.conflict,
+	ambiguous_target: EXIT_CODES.validation,
+	operation_rejected: EXIT_CODES.validation,
+	repack_required: EXIT_CODES.validation,
+	author_required: EXIT_CODES.validation,
+	locked: EXIT_CODES.conflict,
+	destination_exists: EXIT_CODES.conflict,
+	transaction_conflict: EXIT_CODES.conflict,
+	integrity_failed: EXIT_CODES.unexpected,
+	renderer_unavailable: EXIT_CODES.validation,
+	internal_error: EXIT_CODES.unexpected
+};
+const exitCodeForError = (code) => ERROR_CODE_EXIT[code];
+/**
+* Every expected failure of a command or tool call. `hint` names the next
+* step (re-read, pass a flag); `details` carries structured context such as
+* the skipped operations of a refused batch.
+*/
+var FolioCliError = class extends TaggedError("FolioCliError") {};
+/** Build a {@link FolioCliError} without spelling absent optional fields. */
+const cliError = ({ code, message, hint, details }) => new FolioCliError({
+	code,
+	message,
+	...hint !== void 0 && { hint },
+	...details !== void 0 && { details }
+});
+//#endregion
+export { EXIT_CODES, FOLIO_CLI_ERROR_CODES, FolioCliError, cliError, exitCodeEntries, exitCodeForError };

package/dist/execute-read.d.ts

@@ -0,0 +1,64 @@
+import { FolioCliError } from "./errors.js";
+import { FolioFileToolSpec } from "./registry.js";
+import { Result } from "better-result";
+//#region src/execute-read.d.ts
+/** One call against one file: the envelope plus the tool's own arguments. */
+type FileToolCall = {
+  path: string;
+  /** When present, the call is refused unless the file still has this version. */
+  fileVersion?: string | undefined;
+  args: Readonly<Record<string, unknown>>;
+};
+/** Per-surface limits on what one read returns. */
+type FolioReadBounds = {
+  /** Page size when `read_document` passes none; `null` returns every block. */
+  defaultMaxBlocks: number | null;
+  /** Most `find_text` matches returned; the rest are counted, not listed. */
+  maxMatches: number;
+  /** Largest serialized result; `null` for no limit. */
+  maxResponseBytes: number | null;
+};
+declare const CLI_READ_BOUNDS: FolioReadBounds;
+/** The data every file read returns: which file, at which version, and the result. */
+type FileReadData = {
+  path: string;
+  fileVersion: string;
+  result: unknown;
+};
+/**
+ * Where a block id comes from. `package` ids are the paragraph's own
+ * `w14:paraId`; `synthetic` ids are derived from the paragraph's text and
+ * position, valid only for the fileVersion they were read at.
+ */
+type FolioBlockIdSource = "package" | "synthetic";
+type BlockIdSources = ReadonlyMap<string, FolioBlockIdSource>;
+type ReadCursor = {
+  fileVersion: string;
+  afterBlockId: string;
+};
+declare const encodeReadCursor: ({ fileVersion, afterBlockId }: ReadCursor) => string;
+type ReadDocumentPage = {
+  blocks: unknown[];
+  totalBlocks: number;
+  truncated: boolean;
+  nextCursor?: string;
+};
+type PageReadDocumentOptions = {
+  blocks: readonly unknown[];
+  sources: BlockIdSources;
+  fileVersion: string;
+  args: Readonly<Record<string, unknown>>;
+  bounds: FolioReadBounds;
+  /** Bytes the page's blocks may take; `null` for no limit. */
+  pageByteBudget: number | null;
+};
+/**
+ * Page `read_document`'s blocks by count and serialized size. A cursor names
+ * the last block of the previous page and the version it was read at, so a
+ * page from one version never continues on another.
+ */
+declare const pageReadDocument: ({ blocks, sources, fileVersion, args, bounds, pageByteBudget }: PageReadDocumentOptions) => Result<ReadDocumentPage, FolioCliError>;
+/** Run one read tool, or a compare without a destination. Never writes. */
+declare const executeReadTool: (tool: FolioFileToolSpec, call: FileToolCall, bounds: FolioReadBounds) => Promise<Result<FileReadData, FolioCliError>>;
+//#endregion
+export { CLI_READ_BOUNDS, FileReadData, FileToolCall, FolioBlockIdSource, FolioReadBounds, encodeReadCursor, executeReadTool, pageReadDocument };

package/dist/execute-read.js

@@ -0,0 +1,220 @@
+import { checkExpectedVersion, openReviewer, readDocumentFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { MAX_READ_BLOCKS } from "./registry.js";
+import { Result, panic } from "better-result";
+import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
+import { compareDocxVersions, formatVersionDiffForLLM } from "@stll/folio-agents/compare";
+import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
+import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+//#region src/execute-read.ts
+const CLI_READ_BOUNDS = {
+	defaultMaxBlocks: null,
+	maxMatches: 200,
+	maxResponseBytes: null
+};
+const idSourceOf = ({ idStability }) => idStability === "positional" ? "synthetic" : "package";
+const blockIdSources = (reviewer) => new Map(reviewer.snapshot().blocks.map((block) => [block.id, idSourceOf(block)]));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const blockIdOf = (block) => isRecord(block) && typeof block["blockId"] === "string" ? block["blockId"] : void 0;
+/** Label each block of a read with where its id comes from. */
+const labelBlocks = (blocks, sources) => blocks.map((block) => {
+	const blockId = blockIdOf(block);
+	if (blockId === void 0 || !isRecord(block)) return block;
+	return {
+		...block,
+		blockIdSource: sources.get(blockId) ?? "synthetic"
+	};
+});
+const encodeReadCursor = ({ fileVersion, afterBlockId }) => Buffer.from(JSON.stringify({
+	v: fileVersion,
+	a: afterBlockId
+}), "utf8").toString("base64url");
+const decodeReadCursor = (cursor) => {
+	const parsed = Result.try(() => JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")));
+	if (parsed.isErr() || !isRecord(parsed.value)) return null;
+	const { v, a } = parsed.value;
+	return typeof v === "string" && typeof a === "string" ? {
+		fileVersion: v,
+		afterBlockId: a
+	} : null;
+};
+const invalidInput = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message,
+	hint
+});
+const byteLength = (value) => Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+/** Room kept in a paged response for its envelope fields and `nextCursor`. */
+const PAGE_ENVELOPE_RESERVE_BYTES = 512;
+/**
+* Page `read_document`'s blocks by count and serialized size. A cursor names
+* the last block of the previous page and the version it was read at, so a
+* page from one version never continues on another.
+*/
+const pageReadDocument = ({ blocks, sources, fileVersion, args, bounds, pageByteBudget }) => {
+	const { maxBlocks, cursor } = args;
+	if (maxBlocks !== void 0 && (typeof maxBlocks !== "number" || !Number.isInteger(maxBlocks) || maxBlocks < 1 || maxBlocks > 1e3)) return Result.err(invalidInput(`maxBlocks must be an integer from 1 to ${MAX_READ_BLOCKS}.`));
+	let start = 0;
+	if (cursor !== void 0) {
+		const decoded = typeof cursor === "string" ? decodeReadCursor(cursor) : null;
+		if (decoded === null) return Result.err(invalidInput("cursor is not a nextCursor from read_document."));
+		if (decoded.fileVersion !== fileVersion) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.staleVersion,
+			message: "The document changed after this cursor was issued.",
+			hint: "Read again from the start, without a cursor.",
+			details: {
+				expected: decoded.fileVersion,
+				actual: fileVersion
+			}
+		}));
+		const index = blocks.findIndex((block) => blockIdOf(block) === decoded.afterBlockId);
+		if (index === -1) return Result.err(invalidInput("cursor names a block this version does not have."));
+		start = index + 1;
+	}
+	const limit = typeof maxBlocks === "number" ? maxBlocks : bounds.defaultMaxBlocks;
+	const end = limit === null ? blocks.length : Math.min(blocks.length, start + limit);
+	const labelled = labelBlocks(blocks.slice(start, end), sources);
+	const page = [];
+	let bytes = 0;
+	for (const block of labelled) {
+		bytes += byteLength(block);
+		if (pageByteBudget !== null && bytes > pageByteBudget && page.length > 0) break;
+		page.push(block);
+	}
+	while (start + page.length < blocks.length && page.length > 0 && blockIdOf(page.at(-1)) === void 0) page.pop();
+	const lastBlockId = blockIdOf(page.at(-1));
+	const truncated = start + page.length < blocks.length;
+	if (truncated && lastBlockId === void 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.internal,
+		message: "read_document page has no block with an id; cannot issue a cursor."
+	}));
+	return Result.ok({
+		blocks: page,
+		totalBlocks: blocks.length,
+		truncated,
+		...truncated && lastBlockId !== void 0 && { nextCursor: encodeReadCursor({
+			fileVersion,
+			afterBlockId: lastBlockId
+		}) }
+	});
+};
+const unexpectedShape = (tool) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${tool} returned an unexpected result shape.`
+});
+const runAgentRead = ({ tool, reviewer, fileVersion, args, bounds, pageByteBudget }) => {
+	const bridge = createReviewerBridge(reviewer);
+	const isReadDocument = tool.agentTool === FOLIO_AGENT_TOOL_NAMES.readDocument;
+	const agentArgs = isReadDocument ? {} : args;
+	const executed = executeFolioToolCallUntyped(tool.agentTool, agentArgs, bridge);
+	if (!executed.ok) return Result.err(invalidInput(executed.error));
+	const { result } = executed;
+	if (isReadDocument) {
+		if (!Array.isArray(result)) return Result.err(unexpectedShape(tool.name));
+		return pageReadDocument({
+			blocks: result,
+			sources: blockIdSources(reviewer),
+			fileVersion,
+			args,
+			bounds,
+			pageByteBudget
+		});
+	}
+	if (tool.agentTool === FOLIO_AGENT_TOOL_NAMES.readSection) {
+		if (!isRecord(result) || !Array.isArray(result["blocks"])) return Result.err(unexpectedShape(tool.name));
+		return Result.ok({
+			...result,
+			blocks: labelBlocks(result["blocks"], blockIdSources(reviewer))
+		});
+	}
+	if (tool.agentTool === FOLIO_AGENT_TOOL_NAMES.findText) {
+		if (!isRecord(result) || !Array.isArray(result["matches"])) return Result.err(unexpectedShape(tool.name));
+		const matches = result["matches"];
+		return Result.ok(matches.length <= bounds.maxMatches ? result : {
+			...result,
+			matches: matches.slice(0, bounds.maxMatches),
+			truncated: true
+		});
+	}
+	return Result.ok(result);
+};
+const tooLarge = (tool, limit) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.tooLarge,
+	message: `The ${tool} result exceeds the ${limit}-byte response limit.`,
+	hint: "Narrow the read: get_document_outline then read_section, a scoped find_text, or read_document paging."
+});
+/** Diff two files without writing: the structured diff plus a compact rendering. */
+const compareFiles = async (tool, call, bounds) => {
+	const revisedPath = call.args["revisedPath"];
+	if (typeof revisedPath !== "string" || revisedPath === "") return Result.err(invalidInput("compare_documents needs revisedPath."));
+	const base = await readDocumentFile(call.path);
+	if (base.isErr()) return Result.err(base.error);
+	const baseVersion = checkExpectedVersion(base.value, call.fileVersion);
+	if (baseVersion.isErr()) return Result.err(baseVersion.error);
+	const revised = await readDocumentFile(revisedPath);
+	if (revised.isErr()) return Result.err(revised.error);
+	const expectedRevised = call.args["revisedFileVersion"];
+	const revisedVersion = checkExpectedVersion(revised.value, typeof expectedRevised === "string" ? expectedRevised : void 0);
+	if (revisedVersion.isErr()) return Result.err(revisedVersion.error);
+	const diff = await Result.tryPromise({
+		try: () => compareDocxVersions(base.value.bytes.slice().buffer, revised.value.bytes.slice().buffer),
+		catch: (error) => cliError({
+			code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+			message: `The documents could not be compared: ${error instanceof Error ? error.message : String(error)}`
+		})
+	});
+	if (diff.isErr()) return Result.err(diff.error);
+	const data = {
+		path: base.value.path,
+		fileVersion: base.value.fileVersion,
+		revised: {
+			path: revised.value.path,
+			fileVersion: revised.value.fileVersion
+		},
+		result: {
+			text: formatVersionDiffForLLM(diff.value),
+			diff: diff.value
+		}
+	};
+	return bounds.maxResponseBytes !== null && byteLength(data) > bounds.maxResponseBytes ? Result.err(tooLarge(tool.name, bounds.maxResponseBytes)) : Result.ok(data);
+};
+const readWithAgentTool = async (tool, call, bounds) => {
+	const file = await readDocumentFile(call.path);
+	if (file.isErr()) return Result.err(file.error);
+	const version = checkExpectedVersion(file.value, call.fileVersion);
+	if (version.isErr()) return Result.err(version.error);
+	const reviewer = await openReviewer(file.value);
+	if (reviewer.isErr()) return Result.err(reviewer.error);
+	const { path, fileVersion } = file.value;
+	const result = runAgentRead({
+		tool,
+		reviewer: reviewer.value,
+		fileVersion,
+		args: call.args,
+		bounds,
+		pageByteBudget: bounds.maxResponseBytes === null ? null : bounds.maxResponseBytes - byteLength({
+			path,
+			fileVersion
+		}) - PAGE_ENVELOPE_RESERVE_BYTES
+	});
+	if (result.isErr()) return Result.err(result.error);
+	const data = {
+		path,
+		fileVersion,
+		result: result.value
+	};
+	if (bounds.maxResponseBytes !== null && byteLength(data) > bounds.maxResponseBytes) return Result.err(tooLarge(tool.name, bounds.maxResponseBytes));
+	return Result.ok(data);
+};
+/** Run one read tool, or a compare without a destination. Never writes. */
+const executeReadTool = async (tool, call, bounds) => {
+	switch (tool.type) {
+		case "agentRead": return await readWithAgentTool(tool, call, bounds);
+		case "compare": return await compareFiles(tool, call, bounds);
+		case "agentWrite":
+		case "resolveChanges": return panic("A write tool reached the read executor", { tool: tool.name });
+		default: return panic("Unhandled tool type", { unreachable: tool });
+	}
+};
+//#endregion
+export { CLI_READ_BOUNDS, encodeReadCursor, executeReadTool, pageReadDocument };

package/dist/execute-write.d.ts

@@ -0,0 +1,36 @@
+import { FolioCliError } from "./errors.js";
+import { FolioFileToolSpec } from "./registry.js";
+import { FileToolCall } from "./execute-read.js";
+import { WriteDestination } from "./transaction.js";
+import { Result } from "better-result";
+import { FolioAIEditApplyMode } from "@stll/folio-core/server";
+//#region src/execute-write.d.ts
+/** Everything about a write that is not the tool's own arguments. */
+type WriteOptions = {
+  destination: WriteDestination;
+  /** Already resolved: a write never proceeds without one. */
+  author: string;
+  /** The transaction's one UTC timestamp. */
+  date: string;
+  /** Whether a save the selective patch cannot express may rewrite every part. */
+  repack: "allow" | "refuse";
+  /** Take the lease over from another live holder. */
+  force: boolean;
+  /**
+   * `required`: the call must name the source's fileVersion (every MCP
+   * write, and the CLI unless `--no-expect-version`). `waived`: explicitly
+   * skipped.
+   */
+  sourcePrecondition: "required" | "waived";
+  /** Idempotency key; generated when absent. */
+  txId: string | undefined;
+  journalPath: string | undefined;
+  /** For tools whose edit mode is selectable. */
+  mode: FolioAIEditApplyMode;
+};
+/** How a transaction's bytes were produced. */
+type SaveStrategy = "selective" | "full-repack" | "redline";
+/** Run one write tool as a transaction and return its receipt. */
+declare const executeWriteTool: (tool: FolioFileToolSpec, call: FileToolCall, options: WriteOptions) => Promise<Result<Readonly<Record<string, unknown>>, FolioCliError>>;
+//#endregion
+export { SaveStrategy, type WriteDestination, WriteOptions, executeWriteTool };