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

package/dist/execute-write.js

@@ -0,0 +1,449 @@
+import { checkExpectedVersion, errnoCode, openReviewer, readDocumentFile, sameFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { findCommit, journalPathFor, recoverStages } from "./journal.js";
+import { acquireLease } from "./lock.js";
+import { diffPackages, nextRevisionIdSeed } from "./package-parts.js";
+import { SIDECAR_DIRECTORY, unsafePath } from "./sidecar.js";
+import { commitTransaction } from "./transaction.js";
+import { Result, panic } from "better-result";
+import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
+import { generateRedlineDocx } from "@stll/folio-agents/compare";
+import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
+import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+import { createHash, randomUUID } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+//#region src/execute-write.ts
+/**
+* Run one mutating tool call as a transaction: take the destination's lease,
+* settle any crashed stage, replay a committed `txId`, apply the change to a
+* fresh reviewer, save it (selective unless a full repack is allowed), and
+* commit the bytes atomically with a journal line and, in place, a backup.
+*/
+const TX_ID_PATTERN = /^[\w.-]{1,128}$/u;
+const invalidInput = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message,
+	hint
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** JSON with object keys sorted at every depth, for a stable request hash. */
+const canonicalJson = (value) => {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (isRecord(value)) return `{${Object.keys(value).toSorted().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+};
+const STALE_ISSUE_CODES = /* @__PURE__ */ new Set([
+	"missingBlock",
+	"changedBlock",
+	"staleRange",
+	"preconditionFailed",
+	"documentVersionMismatch"
+]);
+/**
+* A batch lands whole or not at all: any skipped operation refuses the
+* transaction. Stale targets are a conflict with current state; an ambiguous
+* `find` or an operation the document cannot take is an input error.
+*/
+const refusalFor = (summary) => {
+	if (!isRecord(summary) || !Array.isArray(summary["skipped"])) return null;
+	if (summary["skipped"].length === 0) return null;
+	const issues = Array.isArray(summary["issues"]) ? summary["issues"] : [];
+	const codes = issues.map((issue) => isRecord(issue) ? issue["code"] : void 0).filter((code) => typeof code === "string" && code !== "atomicBatchRejected");
+	const details = {
+		skipped: summary["skipped"],
+		issues
+	};
+	if (codes.some((code) => typeof code === "string" && STALE_ISSUE_CODES.has(code))) return cliError({
+		code: FOLIO_CLI_ERROR_CODES.staleTarget,
+		message: "An operation's target changed or no longer exists; nothing was written.",
+		hint: "Re-read the document (read, find) and retry with fresh ids, ranges, and fileVersion.",
+		details
+	});
+	if (codes.includes("ambiguousFind")) return cliError({
+		code: FOLIO_CLI_ERROR_CODES.ambiguousTarget,
+		message: "An operation's find text matches more than once in its block; nothing was written.",
+		hint: "Make the find text unique within the block, or target a range returned by find.",
+		details
+	});
+	return cliError({
+		code: FOLIO_CLI_ERROR_CODES.operationRejected,
+		message: "The document refused an operation; nothing was written.",
+		hint: "See error.details.skipped for each operation's reason.",
+		details
+	});
+};
+const saveReviewer = async (reviewer, repack) => {
+	const saved = await Result.tryPromise({
+		try: () => reviewer.save({ repack }),
+		catch: (error) => cliError({
+			code: FOLIO_CLI_ERROR_CODES.internal,
+			message: `The document could not be saved: ${error instanceof Error ? error.message : String(error)}`
+		})
+	});
+	if (saved.isErr()) return Result.err(saved.error);
+	switch (saved.value.type) {
+		case "selective": return Result.ok({
+			bytes: new Uint8Array(saved.value.buffer),
+			saveStrategy: "selective"
+		});
+		case "full-repack": return Result.ok({
+			bytes: new Uint8Array(saved.value.buffer),
+			saveStrategy: "full-repack",
+			repackReason: saved.value.reason
+		});
+		case "repackRefused": return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.repackRequired,
+			message: `This change needs a full repack of the package (${saved.value.reason}); nothing was written.`,
+			hint: "Pass --allow-repack (MCP: allowRepack: true) to rewrite every part.",
+			details: { reason: saved.value.reason }
+		}));
+		default: {
+			const unreachable = saved.value;
+			return panic("Unhandled save result", { unreachable });
+		}
+	}
+};
+const commentExists = (reviewer, commentId) => reviewer.getComments().some((thread) => String(thread.id) === commentId || thread.replies.some((reply) => String(reply.id) === commentId));
+const mutateWithAgentTool = async ({ tool, source, args, options }) => {
+	if (tool.type !== "agentWrite") return panic("mutateWithAgentTool needs an agentWrite tool");
+	const reviewer = await openReviewer(source, options.author);
+	if (reviewer.isErr()) return Result.err(reviewer.error);
+	const idSeed = await nextRevisionIdSeed(source.bytes);
+	if (idSeed.isErr()) return Result.err(idSeed.error);
+	if ((tool.agentTool === FOLIO_AGENT_TOOL_NAMES.replyComment || tool.agentTool === FOLIO_AGENT_TOOL_NAMES.resolveComment) && !commentExists(reviewer.value, args["commentId"])) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.notFound,
+		message: `No comment with id ${JSON.stringify(args["commentId"])}.`,
+		hint: "Take the id from folio comments."
+	}));
+	const bridge = createReviewerBridge(reviewer.value, {
+		mode: tool.editMode === "tracked-or-direct" ? options.mode : "tracked-changes",
+		revisionStamp: {
+			date: options.date,
+			idSeed: idSeed.value
+		}
+	});
+	const executed = executeFolioToolCallUntyped(tool.agentTool, args, bridge);
+	if (!executed.ok) return Result.err(invalidInput(executed.error));
+	const refusal = refusalFor(executed.result);
+	if (refusal !== null) return Result.err(refusal);
+	const saved = await saveReviewer(reviewer.value, options.repack);
+	if (saved.isErr()) return Result.err(saved.error);
+	const receipts = isRecord(executed.result) && Array.isArray(executed.result["receipts"]) ? executed.result["receipts"] : [];
+	return Result.ok({
+		...saved.value,
+		result: executed.result,
+		receipts
+	});
+};
+const isResolveAction = (value) => value === "accept" || value === "reject";
+const resolveChanges = async ({ source, args, options }) => {
+	const { action, ids, all } = args;
+	if (!isResolveAction(action)) return Result.err(invalidInput("resolve_changes needs action \"accept\" or \"reject\"."));
+	const idList = Array.isArray(ids) && ids.every((id) => typeof id === "string") ? ids : void 0;
+	if ((idList !== void 0 && idList.length > 0) === (all === true)) return Result.err(invalidInput("Pass change ids or all, exactly one of them.", "folio accept --id 12 or --all."));
+	const reviewer = await openReviewer(source, options.author);
+	if (reviewer.isErr()) return Result.err(reviewer.error);
+	let resolved;
+	if (all === true) {
+		const count = action === "accept" ? reviewer.value.acceptAll() : reviewer.value.rejectAll();
+		if (count === 0) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.operationRejected,
+			message: "The document has no pending tracked changes; nothing was written."
+		}));
+		resolved = count;
+	} else {
+		const selected = idList ?? [];
+		const known = new Set(reviewer.value.getChanges().map(({ id }) => String(id)));
+		const missing = selected.filter((id) => !known.has(id));
+		if (missing.length > 0) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.notFound,
+			message: `No pending change with id ${missing.join(", ")}.`,
+			hint: "Take ids from folio changes.",
+			details: { missing }
+		}));
+		for (const id of selected) if (!(action === "accept" ? reviewer.value.acceptChange(Number(id)) : reviewer.value.rejectChange(Number(id)))) return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.operationRejected,
+			message: `Change ${id} could not be ${action}ed; nothing was written.`
+		}));
+		resolved = selected;
+	}
+	const saved = await saveReviewer(reviewer.value, options.repack);
+	if (saved.isErr()) return Result.err(saved.error);
+	return Result.ok({
+		...saved.value,
+		result: {
+			action,
+			resolved,
+			remaining: reviewer.value.getChanges().length
+		},
+		receipts: []
+	});
+};
+const writeRedline = async ({ source, args, options }) => {
+	const revisedPath = args["revisedPath"];
+	if (typeof revisedPath !== "string" || revisedPath === "") return Result.err(invalidInput("compare_documents needs revisedPath."));
+	const revised = await readDocumentFile(revisedPath);
+	if (revised.isErr()) return Result.err(revised.error);
+	const revisedVersion = args["revisedFileVersion"];
+	const version = checkExpectedVersion(revised.value, typeof revisedVersion === "string" ? revisedVersion : void 0);
+	if (version.isErr()) return Result.err(version.error);
+	const redline = await Result.tryPromise({
+		try: () => generateRedlineDocx(source.bytes.slice().buffer, revised.value.bytes.slice().buffer, { author: options.author }),
+		catch: (error) => cliError({
+			code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+			message: `The documents could not be compared: ${error instanceof Error ? error.message : String(error)}`
+		})
+	});
+	if (redline.isErr()) return Result.err(redline.error);
+	const { buffer, applied, skipped, unprocessedStories } = redline.value;
+	return Result.ok({
+		bytes: new Uint8Array(buffer),
+		saveStrategy: "redline",
+		result: {
+			applied: applied.length,
+			skipped,
+			unprocessedStories
+		},
+		receipts: [],
+		inputs: { revised: {
+			path: revised.value.path,
+			fileVersion: revised.value.fileVersion
+		} }
+	});
+};
+const mutate = (options) => {
+	switch (options.tool.type) {
+		case "agentWrite": return mutateWithAgentTool(options);
+		case "resolveChanges": return resolveChanges(options);
+		case "compare": return writeRedline(options);
+		case "agentRead": return panic("A read tool reached the write executor", { tool: options.tool.name });
+		default: {
+			const unreachable = options.tool;
+			return panic("Unhandled tool type", { unreachable });
+		}
+	}
+};
+const DOCX_NAME = /\.docx$/iu;
+const invalidDestination = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidDestination,
+	message,
+	hint
+});
+/**
+* A write lands only on a `.docx` whose name does not start with a dot and
+* that is not inside a `.folio` directory, so no tool call can replace a
+* dotfile, a sidecar, or another kind of file.
+*/
+const checkDestinationName = (candidate) => {
+	const name = path.basename(candidate);
+	if (!DOCX_NAME.test(name) || name.startsWith(".")) return Result.err(invalidDestination(`${candidate} is not a writable destination: folio writes only .docx files whose name does not start with a dot.`));
+	if (candidate.split(path.sep).includes(".folio")) return Result.err(invalidDestination(`${candidate} is inside a ${SIDECAR_DIRECTORY} directory.`));
+	return Result.ok();
+};
+const notFound = (message) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.notFound,
+	message
+});
+/**
+* The real path a write goes to: an existing file resolved through its
+* symlinks (it must be a regular file), or a new name in its directory's real
+* path. The name rules apply to the resolved path, so a link cannot redirect
+* a write onto a file the rules refuse.
+*/
+const resolveWritePath = async (requested) => {
+	const absolute = path.resolve(requested);
+	const named = checkDestinationName(absolute);
+	if (named.isErr()) return Result.err(named.error);
+	const real = await Result.tryPromise(() => realpath(absolute));
+	let resolved;
+	if (real.isOk()) {
+		const info = await Result.tryPromise(() => stat(real.value));
+		if (info.isErr() || !info.value.isFile()) return Result.err(invalidDestination(`${absolute} is not a regular file.`));
+		resolved = {
+			path: real.value,
+			identity: {
+				dev: info.value.dev,
+				ino: info.value.ino
+			}
+		};
+	} else if (errnoCode(real.error.cause) === "ENOENT") {
+		const parent = await Result.tryPromise(() => realpath(path.dirname(absolute)));
+		if (parent.isErr()) return Result.err(notFound(`No directory ${path.dirname(absolute)}.`));
+		resolved = {
+			path: path.join(parent.value, path.basename(absolute)),
+			identity: null
+		};
+	} else return Result.err(invalidDestination(`Cannot resolve ${absolute}.`));
+	const resolvedName = checkDestinationName(resolved.path);
+	return resolvedName.isErr() ? Result.err(resolvedName.error) : Result.ok(resolved);
+};
+const identityOfInput = async (inputPath) => {
+	const real = await Result.tryPromise(() => realpath(path.resolve(inputPath)));
+	if (real.isErr()) return Result.err(notFound(`No file at ${path.resolve(inputPath)}.`));
+	const info = await Result.tryPromise(() => stat(real.value));
+	if (info.isErr() || !info.value.isFile()) return Result.err(invalidInput(`${real.value} is not a file.`));
+	return Result.ok({
+		path: real.value,
+		identity: {
+			dev: info.value.dev,
+			ino: info.value.ino
+		}
+	});
+};
+/**
+* Resolve source and destination to real paths and refuse a destination
+* that is the input under another name (a symlink, a hard link, a
+* case-insensitive alias): files are compared by device and inode.
+*/
+const resolveTarget = async (tool, call, destination) => {
+	const source = await identityOfInput(call.path);
+	if (source.isErr()) return Result.err(source.error);
+	if (destination.type === "inPlace") {
+		if (tool.type === "compare") return Result.err(cliError({
+			code: FOLIO_CLI_ERROR_CODES.usage,
+			message: "A redline is written to a new file, never in place.",
+			hint: "Pass -o <redline.docx>."
+		}));
+		const named = checkDestinationName(source.value.path);
+		if (named.isErr()) return Result.err(named.error);
+		return Result.ok({
+			sourcePath: source.value.path,
+			sourceIdentity: source.value.identity,
+			destinationPath: source.value.path
+		});
+	}
+	const target = await resolveWritePath(destination.path);
+	if (target.isErr()) return Result.err(target.error);
+	const inputs = [source.value];
+	const revisedPath = call.args["revisedPath"];
+	if (tool.type === "compare" && typeof revisedPath === "string") {
+		const revised = await identityOfInput(revisedPath);
+		if (revised.isErr()) return Result.err(revised.error);
+		inputs.push(revised.value);
+	}
+	const clash = inputs.find(({ path: inputPath, identity }) => inputPath === target.value.path || target.value.identity !== null && sameFile(identity, target.value.identity));
+	if (clash !== void 0) return Result.err(invalidDestination(`The destination is the input ${clash.path}.`, tool.type === "compare" ? "Write the redline to a new file." : "Use --in-place to change the file itself; it keeps a backup."));
+	return Result.ok({
+		sourcePath: source.value.path,
+		sourceIdentity: source.value.identity,
+		destinationPath: target.value.path
+	});
+};
+/** Run one write tool as a transaction and return its receipt. */
+const executeWriteTool = async (tool, call, options) => {
+	if (options.txId !== void 0 && !TX_ID_PATTERN.test(options.txId)) return Result.err(invalidInput("txId must be 1 to 128 letters, digits, '.', '_' or '-'."));
+	if (options.sourcePrecondition === "required" && call.fileVersion === void 0) return Result.err(invalidInput("A change needs the fileVersion of the file it was read from.", "Pass --expect-version <fileVersion> from your read (MCP: fileVersion), or --no-expect-version to skip the check."));
+	const txId = options.txId ?? randomUUID();
+	const target = await resolveTarget(tool, call, options.destination);
+	if (target.isErr()) return Result.err(target.error);
+	const { sourcePath, sourceIdentity, destinationPath } = target.value;
+	const journalPath = journalPathFor(destinationPath, options.journalPath);
+	const lease = await acquireLease({
+		documentPath: destinationPath,
+		txId,
+		force: options.force
+	});
+	if (lease.isErr()) return Result.err(lease.error);
+	try {
+		const recovered = await recoverStages({
+			documentPath: destinationPath,
+			journalPath,
+			now: options.date
+		});
+		if (recovered.isErr()) return Result.err(recovered.error);
+		const requestHash = createHash("sha256").update(canonicalJson({
+			tool: tool.name,
+			args: call.args,
+			source: sourcePath,
+			destination: destinationPath,
+			mode: options.mode,
+			repack: options.repack
+		})).digest("hex");
+		if (options.txId !== void 0) {
+			const found = await findCommit(journalPath, txId);
+			if (found.isErr()) return Result.err(found.error);
+			const prior = found.value;
+			if (prior !== void 0) return prior.requestHash === requestHash ? Result.ok({
+				...prior.receipt,
+				status: "replayed"
+			}) : Result.err(cliError({
+				code: FOLIO_CLI_ERROR_CODES.transactionConflict,
+				message: `Transaction ${txId} already committed a different request.`,
+				hint: "Use a new txId for a new change."
+			}));
+		}
+		const source = await readDocumentFile(sourcePath);
+		if (source.isErr()) return Result.err(source.error);
+		const expectedIdentity = destinationPath === sourcePath && recovered.value.some(({ action }) => action === "rolledForward") ? source.value.identity : sourceIdentity;
+		if (!sameFile(source.value.identity, expectedIdentity)) return Result.err(unsafePath(`${sourcePath} was replaced while the write started.`));
+		if (destinationPath === sourcePath && source.value.links > 1) return Result.err(unsafePath(`${sourcePath} has other hard links; an in-place write would detach them.`, "Write to a new file with -o instead."));
+		const version = checkExpectedVersion(source.value, call.fileVersion);
+		if (version.isErr()) return Result.err(recovered.value.length === 0 ? version.error : cliError({
+			code: version.error.code,
+			message: version.error.message,
+			hint: version.error.hint,
+			details: {
+				...isRecord(version.error.details) ? version.error.details : {},
+				recovered: recovered.value
+			}
+		}));
+		const mutation = await mutate({
+			tool,
+			source: source.value,
+			args: call.args,
+			options
+		});
+		if (mutation.isErr()) return Result.err(mutation.error);
+		const { bytes, saveStrategy, repackReason, result, receipts, inputs } = mutation.value;
+		const changedParts = await diffPackages(source.value.bytes, bytes);
+		if (changedParts.isErr()) return Result.err(changedParts.error);
+		const receipt = {
+			txId,
+			status: "committed",
+			tool: tool.name,
+			path: destinationPath,
+			fromVersion: source.value.fileVersion,
+			...destinationPath !== sourcePath && { source: {
+				path: sourcePath,
+				fileVersion: source.value.fileVersion
+			} },
+			...inputs,
+			author: options.author,
+			time: options.date,
+			saveStrategy,
+			...repackReason !== void 0 && { repackReason },
+			changedParts: changedParts.value,
+			...recovered.value.length > 0 && { recovered: recovered.value },
+			result
+		};
+		const committed = await commitTransaction({
+			txId,
+			destinationPath,
+			destination: options.destination,
+			sourcePath,
+			sourceIdentity: expectedIdentity,
+			fromVersion: source.value.fileVersion,
+			bytes,
+			verifyLease: lease.value.verify,
+			changedParts: changedParts.value,
+			journalPath,
+			entry: {
+				txId,
+				requestHash,
+				tool: tool.name,
+				fromVersion: source.value.fileVersion,
+				author: options.author,
+				time: options.date,
+				ops: call.args,
+				receipts
+			},
+			receipt
+		});
+		return committed.isErr() ? Result.err(committed.error) : Result.ok(committed.value.receipt);
+	} finally {
+		await lease.value.release();
+	}
+};
+//#endregion
+export { executeWriteTool };

package/dist/flags.d.ts

@@ -0,0 +1,38 @@
+import { FolioCliError } from "./errors.js";
+import { JsonObjectSchema } from "./registry.js";
+import { Result } from "better-result";
+//#region src/flags.d.ts
+/** Largest `--input` document accepted. */
+declare const MAX_INPUT_BYTES: number;
+type FlagValueType = "boolean" | "integer" | "number" | "string" | "strings" | "json";
+type GeneratedFlag = {
+  /** The schema property the flag sets. */
+  property: string;
+  /** `--flag` spelling, without the dashes. */
+  flag: string;
+  valueType: FlagValueType;
+  description: string;
+};
+declare const kebabCase: (name: string) => string;
+/**
+ * One flag per top-level schema property, in declaration order. `flagNames`
+ * renames a property's flag (`{ ids: "id" }` for `--id`).
+ */
+declare const flagsForSchema: (schema: JsonObjectSchema, flagNames?: Readonly<Record<string, string>>) => GeneratedFlag[];
+type CoerceFlagOptions = {
+  flag: GeneratedFlag;
+  raw: string | boolean | readonly string[];
+};
+/** Convert one parsed flag value to the type its schema property declares. */
+declare const coerceFlag: ({ flag, raw }: CoerceFlagOptions) => Result<unknown, FolioCliError>;
+type ReadInputOptions = {
+  source: string;
+  readStdin: () => Promise<string>;
+};
+/**
+ * Read `--input`: `@path` reads a file, `-` reads stdin, anything else is
+ * inline JSON. The result must be a JSON object or array.
+ */
+declare const readInputSource: ({ source, readStdin }: ReadInputOptions) => Promise<Result<Record<string, unknown> | unknown[], FolioCliError>>;
+//#endregion
+export { FlagValueType, GeneratedFlag, MAX_INPUT_BYTES, coerceFlag, flagsForSchema, kebabCase, readInputSource };

package/dist/flags.js

@@ -0,0 +1,102 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result, panic } from "better-result";
+import { readFile } from "node:fs/promises";
+//#region src/flags.ts
+/**
+* Command flags generated from a tool's JSON Schema. Each top-level property
+* becomes `--kebab-case-name`: booleans are switches, numbers and strings take
+* a value, arrays of strings repeat (`--id 3 --id 4`, or `--id 3,4`), and
+* other objects or arrays take a JSON value. `--input` supplies the
+* whole argument object as JSON (inline, `@file`, or `-` for stdin), and
+* flags given alongside it override its fields.
+*/
+/** Largest `--input` document accepted. */
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+const kebabCase = (name) => name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const valueTypeOf = (schema) => {
+	if (!isRecord(schema)) return "json";
+	switch (schema["type"]) {
+		case "boolean": return "boolean";
+		case "integer": return "integer";
+		case "number": return "number";
+		case "string": return "string";
+		case "array": {
+			const items = schema["items"];
+			return isRecord(items) && items["type"] === "string" ? "strings" : "json";
+		}
+		default: return "json";
+	}
+};
+const descriptionOf = (schema) => {
+	if (!isRecord(schema)) return "";
+	return `${typeof schema["description"] === "string" ? schema["description"] : ""}${Array.isArray(schema["enum"]) ? ` One of: ${schema["enum"].join(", ")}.` : ""}`.trim();
+};
+/**
+* One flag per top-level schema property, in declaration order. `flagNames`
+* renames a property's flag (`{ ids: "id" }` for `--id`).
+*/
+const flagsForSchema = (schema, flagNames = {}) => Object.entries(schema.properties).map(([property, propertySchema]) => ({
+	property,
+	flag: flagNames[property] ?? kebabCase(property),
+	valueType: valueTypeOf(propertySchema),
+	description: descriptionOf(propertySchema)
+}));
+const usage = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.usage,
+	message,
+	hint
+});
+/** Convert one parsed flag value to the type its schema property declares. */
+const coerceFlag = ({ flag, raw }) => {
+	if (typeof raw === "boolean") return flag.valueType === "boolean" ? Result.ok(raw) : Result.err(usage(`--${flag.flag} takes a value.`));
+	if (typeof raw !== "string") return flag.valueType === "strings" ? Result.ok(raw.flatMap((value) => value.split(",")).filter((value) => value !== "")) : Result.err(usage(`--${flag.flag} is given more than once.`));
+	switch (flag.valueType) {
+		case "boolean": return Result.err(usage(`--${flag.flag} is a switch and takes no value.`));
+		case "string": return Result.ok(raw);
+		case "strings": return Result.ok(raw.split(",").filter((value) => value !== ""));
+		case "integer":
+		case "number": {
+			const value = Number(raw);
+			if (raw.trim() === "" || !Number.isFinite(value)) return Result.err(usage(`--${flag.flag} expects a number, got ${JSON.stringify(raw)}.`));
+			if (flag.valueType === "integer" && !Number.isInteger(value)) return Result.err(usage(`--${flag.flag} expects an integer, got ${JSON.stringify(raw)}.`));
+			return Result.ok(value);
+		}
+		case "json": {
+			const parsed = Result.try(() => JSON.parse(raw));
+			return parsed.isOk() ? Result.ok(parsed.value) : Result.err(usage(`--${flag.flag} expects a JSON value.`));
+		}
+		default: {
+			const unreachable = flag.valueType;
+			return panic("Unhandled flag value type", { unreachable });
+		}
+	}
+};
+/**
+* Read `--input`: `@path` reads a file, `-` reads stdin, anything else is
+* inline JSON. The result must be a JSON object or array.
+*/
+const readInputSource = async ({ source, readStdin }) => {
+	let text = source;
+	if (source === "-") text = await readStdin();
+	else if (source.startsWith("@")) {
+		const inputPath = source.slice(1);
+		const read = await Result.tryPromise({
+			try: () => readFile(inputPath, "utf8"),
+			catch: () => usage(`Cannot read --input file ${inputPath}.`)
+		});
+		if (read.isErr()) return Result.err(read.error);
+		text = read.value;
+	}
+	if (Buffer.byteLength(text, "utf8") > 16777216) return Result.err(usage(`--input is over the ${MAX_INPUT_BYTES}-byte limit.`));
+	const parsed = Result.try(() => JSON.parse(text));
+	if (parsed.isErr()) return Result.err(usage("--input is not valid JSON.", "Pass inline JSON, @file.json, or - for stdin."));
+	const value = parsed.value;
+	if (Array.isArray(value)) {
+		const items = value;
+		return Result.ok(items);
+	}
+	return isRecord(value) ? Result.ok(value) : Result.err(usage("--input must be a JSON object or array."));
+};
+//#endregion
+export { MAX_INPUT_BYTES, coerceFlag, flagsForSchema, kebabCase, readInputSource };

package/dist/journal.d.ts

@@ -0,0 +1,82 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+//#region src/journal.d.ts
+type JournalCommit = {
+  type: "commit";
+  txId: string;
+  /** Hash of the request, so a retry with the same txId but other arguments is refused. */
+  requestHash: string;
+  tool: string;
+  /** The destination file. */
+  path: string;
+  fromVersion: string;
+  toVersion: string;
+  /** The destination's version before the rename; `null` when it did not exist. */
+  destinationVersionBefore: string | null;
+  /** The staged file's name, beside the destination. */
+  stage: string;
+  author: string;
+  time: string;
+  /** The tool arguments the transaction applied. */
+  ops: unknown;
+  /** Per-operation receipts from the document-operation contract, when the tool has them. */
+  receipts: readonly unknown[];
+  /** What the command returned, replayed verbatim for a retry with the same txId. */
+  receipt: Readonly<Record<string, unknown>>;
+};
+declare const RECOVERY_DISCARD_REASONS: readonly ["notJournaled", "otherDocument", "notRegularFile", "stageChanged", "invalidPackage", "destinationMoved", "leaseLost", "renameRefused"];
+type RecoveryDiscardReason = (typeof RECOVERY_DISCARD_REASONS)[number];
+type JournalRecovery = {
+  type: "recovery";
+  txId: string;
+  path: string;
+  time: string;
+} & ({
+  action: "rolledForward";
+} | {
+  action: "discarded";
+  reason: RecoveryDiscardReason;
+});
+type JournalEntry = JournalCommit | JournalRecovery;
+/** The fields of a commit line recovery and replay read back. */
+type CommittedTransaction = {
+  txId: string;
+  path: string;
+  requestHash: string;
+  toVersion: string;
+  destinationVersionBefore: string | null;
+  receipt: Readonly<Record<string, unknown>>;
+};
+declare const journalPathFor: (documentPath: string, override: string | undefined) => string;
+/** Append one line and sync it to disk before returning. */
+declare const appendJournal: (journalPath: string, entry: JournalEntry) => Promise<Result<void, FolioCliError>>;
+/**
+ * The committed transaction with `txId`, if the journal has one and recovery
+ * did not discard it. Torn or foreign lines (a crash mid-append) are skipped.
+ * A journal (or `.folio`) that is a symlink or hard link is refused.
+ */
+declare const findCommit: (journalPath: string, txId: string) => Promise<Result<CommittedTransaction | undefined, FolioCliError>>;
+declare const stagePrefixFor: (documentPath: string) => string;
+declare const stagePathFor: (documentPath: string, txId: string) => string;
+type RecoveryAction = {
+  txId: string;
+  action: "rolledForward";
+} | {
+  txId: string;
+  action: "discarded";
+  reason: RecoveryDiscardReason;
+};
+type RecoverStagesOptions = {
+  documentPath: string;
+  journalPath: string;
+  now: string;
+};
+/**
+ * Settle every stage a crashed transaction left beside `documentPath`. The
+ * caller holds the document's lease, so no live transaction owns a stage.
+ * Removing a discarded stage unlinks the name only; a symlink's target is
+ * never touched.
+ */
+declare const recoverStages: ({ documentPath, journalPath, now }: RecoverStagesOptions) => Promise<Result<RecoveryAction[], FolioCliError>>;
+//#endregion
+export { CommittedTransaction, JournalCommit, JournalEntry, JournalRecovery, RECOVERY_DISCARD_REASONS, RecoveryAction, RecoveryDiscardReason, appendJournal, findCommit, journalPathFor, recoverStages, stagePathFor, stagePrefixFor };