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

package/dist/cli.js

@@ -0,0 +1,440 @@
+import { EXIT_CODES, FOLIO_CLI_ERROR_CODES, cliError, exitCodeEntries, exitCodeForError } from "./errors.js";
+import { CLI_READ_BOUNDS, executeReadTool } from "./execute-read.js";
+import { executeWriteTool } from "./execute-write.js";
+import { coerceFlag, flagsForSchema, readInputSource } from "./flags.js";
+import { serveFolioMcp } from "./mcp.js";
+import { OUTPUT_FORMATS, failureEnvelope, isOutputFormat, renderEnvelope, successEnvelope } from "./output.js";
+import { version } from "./package.js";
+import { runRender, runServe } from "./preview-commands.js";
+import { resolveAuthor, resolveTransactionDate } from "./provenance.js";
+import { findCommand, listCommands, toolAccess } from "./registry.js";
+import { resolveRoots } from "./roots.js";
+import { Result } from "better-result";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+/**
+* `folio`: the command line over the file tool registry. Each registry
+* command parses its generated flags, runs the same executor the MCP server
+* uses, and prints the shared envelope.
+*/
+const COMMON_FLAGS = [
+	{
+		flag: "output",
+		description: `Output format: ${OUTPUT_FORMATS.join(" or ")} (default: text on a terminal, json otherwise).`,
+		option: { type: "string" }
+	},
+	{
+		flag: "input",
+		description: "All arguments as a JSON object: inline, @file.json, or - for stdin.",
+		option: { type: "string" }
+	},
+	{
+		flag: "expect-version",
+		description: "Refuse unless the file's SHA-256 fileVersion is this value.",
+		option: { type: "string" }
+	},
+	{
+		flag: "help",
+		description: "Show help for this command.",
+		option: {
+			type: "boolean",
+			short: "h"
+		}
+	}
+];
+const WRITE_FLAGS = [
+	{
+		flag: "in-place",
+		description: "Write the change to the file itself, keeping a backup in .folio/backups.",
+		option: { type: "boolean" }
+	},
+	{
+		flag: "out",
+		description: "Write the result to this path instead (refused if it exists, unless --overwrite).",
+		option: {
+			type: "string",
+			short: "o"
+		}
+	},
+	{
+		flag: "overwrite",
+		description: "Let -o replace an existing file; needs --expect-destination-version. The replaced file is backed up.",
+		option: { type: "boolean" }
+	},
+	{
+		flag: "expect-destination-version",
+		description: "The fileVersion of the file -o --overwrite replaces; refused if it changed.",
+		option: { type: "string" }
+	},
+	{
+		flag: "no-expect-version",
+		description: "Change the file without naming its fileVersion. A change otherwise needs --expect-version.",
+		option: { type: "boolean" }
+	},
+	{
+		flag: "author",
+		description: "Author of the change (default: FOLIO_AUTHOR, then git user.name).",
+		option: { type: "string" }
+	},
+	{
+		flag: "date",
+		description: "ISO-8601 timestamp for the change (default: now), for reproducible output.",
+		option: { type: "string" }
+	},
+	{
+		flag: "allow-repack",
+		description: "Allow rewriting the whole package when the edit cannot be patched in.",
+		option: { type: "boolean" }
+	},
+	{
+		flag: "tx-id",
+		description: "Idempotency key: re-running a committed transaction returns its receipt.",
+		option: { type: "string" }
+	},
+	{
+		flag: "force",
+		description: "Take the write lease over from another live holder.",
+		option: { type: "boolean" }
+	},
+	{
+		flag: "journal",
+		description: "Journal file (default: .folio/journal.jsonl beside the destination).",
+		option: { type: "string" }
+	}
+];
+const DIRECT_FLAG = {
+	flag: "direct",
+	description: "Edit the text directly instead of as tracked changes.",
+	option: { type: "boolean" }
+};
+const usageError = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.usage,
+	message,
+	hint
+});
+const writeFlagsFor = ({ tool }) => {
+	if (toolAccess(tool) === "read") return [];
+	return tool.type === "agentWrite" && tool.editMode === "tracked-or-direct" ? [...WRITE_FLAGS, DIRECT_FLAG] : WRITE_FLAGS;
+};
+const generatedFlags = ({ tool, command }) => {
+	const bound = /* @__PURE__ */ new Set([...Object.keys(command.preset ?? {}), ...(command.positionals ?? []).map(({ property }) => property)]);
+	return flagsForSchema(tool.argsSchema, command.flagNames).filter(({ property }) => !bound.has(property));
+};
+const parseOptions = (resolved) => {
+	const options = {};
+	for (const { flag, option } of [...COMMON_FLAGS, ...writeFlagsFor(resolved)]) options[flag] = option;
+	for (const { flag, valueType } of generatedFlags(resolved)) options[flag] = valueType === "boolean" ? { type: "boolean" } : {
+		type: "string",
+		...valueType === "strings" && { multiple: true }
+	};
+	return options;
+};
+const wrapText = (value, indent) => value.replaceAll("\n", `\n${indent}`);
+const usageLine = ({ command }) => [
+	"folio",
+	command.name,
+	"<file>",
+	...(command.positionals ?? []).map(({ name }) => `<${name}>`),
+	"[flags]"
+].join(" ");
+const rootHelp = () => {
+	const commands = listCommands().map(({ command }) => `  ${command.name.padEnd(12)}${command.summary}`);
+	const exitCodes = exitCodeEntries().map(({ code, meaning }) => `  ${String(code).padEnd(4)}${meaning}`);
+	return [
+		`folio ${version}: read, review, and redline .docx files.`,
+		"",
+		"Usage: folio <command> <file> [flags]",
+		"",
+		"Commands:",
+		...commands,
+		`  ${"render".padEnd(12)}Render pages to PDF, PNG, or HTML`,
+		`  ${"serve".padEnd(12)}Serve a read-only live preview on 127.0.0.1`,
+		`  ${"mcp".padEnd(12)}Serve these tools over MCP on stdio`,
+		"",
+		"Every command prints { ok, data } or { ok, error: { code, message, hint } }.",
+		"A change is written only with --in-place or -o <path>, as tracked changes unless --direct.",
+		"Run folio <command> --help for its flags.",
+		"",
+		"Exit codes:",
+		...exitCodes,
+		""
+	].join("\n");
+};
+const commandHelp = (resolved) => {
+	const flags = [...generatedFlags(resolved).map(({ flag, description, valueType }) => ({
+		name: valueType === "boolean" ? `--${flag}` : `--${flag} <${valueType}>`,
+		description
+	})), ...[...writeFlagsFor(resolved), ...COMMON_FLAGS].map(({ flag, description, option }) => ({
+		name: `${option.short === void 0 ? "" : `-${option.short}, `}--${flag}${option.type === "boolean" ? "" : " <value>"}`,
+		description
+	}))];
+	return [
+		`Usage: ${usageLine(resolved)}`,
+		"",
+		resolved.command.summary,
+		"",
+		wrapText(resolved.tool.description, ""),
+		"",
+		"Flags:",
+		...flags.map(({ name, description }) => `  ${name}\n      ${wrapText(description, "      ")}`),
+		""
+	].join("\n");
+};
+const stringValue = (value) => typeof value === "string" ? value : void 0;
+const flagValue = (value) => {
+	if (!Array.isArray(value)) return value;
+	return value.filter((entry) => typeof entry === "string");
+};
+const buildArguments = async ({ resolved, values, positionals, io }) => {
+	const { command } = resolved;
+	const [file, ...rest] = positionals;
+	const named = command.positionals ?? [];
+	if (file === void 0 || rest.length < named.length) return Result.err(usageError(`Usage: ${usageLine(resolved)}.`));
+	if (rest.length > named.length) return Result.err(usageError(`Unexpected argument ${JSON.stringify(rest[named.length])}.`));
+	let args = {};
+	const input = stringValue(values["input"]);
+	if (input !== void 0) {
+		const parsed = await readInputSource({
+			source: input,
+			readStdin: io.readStdin
+		});
+		if (parsed.isErr()) return Result.err(parsed.error);
+		if (Array.isArray(parsed.value)) {
+			if (command.inputArrayProperty === void 0) return Result.err(usageError("--input must be a JSON object for this command."));
+			args = { [command.inputArrayProperty]: parsed.value };
+		} else args = { ...parsed.value };
+	}
+	for (const flag of generatedFlags(resolved)) {
+		const raw = flagValue(values[flag.flag]);
+		if (raw === void 0) continue;
+		const coerced = coerceFlag({
+			flag,
+			raw
+		});
+		if (coerced.isErr()) return Result.err(coerced.error);
+		args[flag.property] = coerced.value;
+	}
+	named.forEach(({ property }, index) => {
+		args[property] = rest[index];
+	});
+	return Result.ok({
+		file,
+		expectVersion: stringValue(values["expect-version"]),
+		args: {
+			...args,
+			...command.preset
+		}
+	});
+};
+/** `--in-place` or `-o`, exactly one; `null` when neither is given. */
+const destinationFrom = (values) => {
+	const inPlace = values["in-place"] === true;
+	const out = stringValue(values["out"]);
+	if (inPlace && out !== void 0) return Result.err(usageError("Pass --in-place or -o <path>, not both."));
+	const expectedVersion = stringValue(values["expect-destination-version"]);
+	if ((values["overwrite"] === true || expectedVersion !== void 0) && out === void 0) return Result.err(usageError("--overwrite and --expect-destination-version only apply to -o <path>."));
+	if (inPlace) return Result.ok({ type: "inPlace" });
+	if (out !== void 0) return Result.ok({
+		type: "file",
+		path: out,
+		overwrite: values["overwrite"] === true,
+		expectedVersion
+	});
+	return Result.ok(null);
+};
+const defaultFormat = (io) => io.isTTY ? "text" : "json";
+/** The `--output` value named in raw argv, so a parse failure still prints in it. */
+const requestedFormat = (argv, io) => {
+	const index = argv.indexOf("--output");
+	const value = argv.find((arg) => arg.startsWith("--output="))?.slice(9) ?? (index === -1 ? void 0 : argv[index + 1]);
+	return isOutputFormat(value) ? value : defaultFormat(io);
+};
+const emit = ({ io, format, tool, result }) => {
+	const rendered = renderEnvelope({
+		envelope: result.isOk() ? successEnvelope(result.value) : failureEnvelope(result.error),
+		format,
+		tool
+	});
+	if (rendered.stdout !== "") io.stdout(rendered.stdout);
+	if (rendered.stderr !== "") io.stderr(rendered.stderr);
+	return result.isOk() ? EXIT_CODES.ok : exitCodeForError(result.error.code);
+};
+const execute = async ({ resolved, values, built, io }) => {
+	const { tool, command } = resolved;
+	const call = {
+		path: built.file,
+		fileVersion: built.expectVersion,
+		args: built.args
+	};
+	const access = toolAccess(tool);
+	if (access === "read") return await executeReadTool(tool, call, CLI_READ_BOUNDS);
+	const destination = destinationFrom(values);
+	if (destination.isErr()) return destination;
+	if (destination.value === null) {
+		if (access === "readOrWrite") return await executeReadTool(tool, call, CLI_READ_BOUNDS);
+		return Result.err(usageError(`folio ${command.name} changes the document: pass --in-place or -o <path>.`, "--in-place keeps a backup in .folio/backups beside the file."));
+	}
+	const author = resolveAuthor({
+		explicit: stringValue(values["author"]),
+		env: io.env,
+		cwd: io.cwd
+	});
+	if (author.isErr()) return author;
+	const date = resolveTransactionDate(stringValue(values["date"]));
+	if (date.isErr()) return date;
+	const waived = values["no-expect-version"] === true;
+	if (waived && built.expectVersion !== void 0) return Result.err(usageError("Pass --expect-version or --no-expect-version, not both."));
+	return await executeWriteTool(tool, call, {
+		sourcePrecondition: waived ? "waived" : "required",
+		destination: destination.value,
+		author: author.value,
+		date: date.value,
+		repack: values["allow-repack"] === true ? "allow" : "refuse",
+		force: values["force"] === true,
+		txId: stringValue(values["tx-id"]),
+		journalPath: stringValue(values["journal"]),
+		mode: values["direct"] === true ? "direct" : "tracked-changes"
+	});
+};
+const runCommand = async (resolved, rest, io) => {
+	const fallbackFormat = requestedFormat(rest, io);
+	const parsed = Result.try({
+		try: () => parseArgs({
+			args: [...rest],
+			options: parseOptions(resolved),
+			allowPositionals: true,
+			strict: true
+		}),
+		catch: (error) => usageError(error instanceof Error ? error.message : String(error), `Run folio ${resolved.command.name} --help.`)
+	});
+	if (parsed.isErr()) return emit({
+		io,
+		format: fallbackFormat,
+		tool: resolved.tool.name,
+		result: parsed
+	});
+	const { values, positionals } = parsed.value;
+	if (values["help"] === true) {
+		io.stdout(commandHelp(resolved));
+		return EXIT_CODES.ok;
+	}
+	const output = values["output"];
+	if (output !== void 0 && !isOutputFormat(output)) return emit({
+		io,
+		format: defaultFormat(io),
+		tool: resolved.tool.name,
+		result: Result.err(usageError(`--output must be ${OUTPUT_FORMATS.join(" or ")}.`))
+	});
+	const format = output ?? defaultFormat(io);
+	const built = await buildArguments({
+		resolved,
+		values,
+		positionals,
+		io
+	});
+	if (built.isErr()) return emit({
+		io,
+		format,
+		tool: resolved.tool.name,
+		result: built
+	});
+	const result = await execute({
+		resolved,
+		values,
+		built: built.value,
+		io
+	});
+	return emit({
+		io,
+		format,
+		tool: resolved.tool.name,
+		result
+	});
+};
+const MCP_HELP = [
+	"Usage: folio mcp [--root <dir>]... [--author <name>]",
+	"",
+	"Serve the folio tools over MCP on stdin/stdout. Diagnostics go to stderr.",
+	"",
+	"Flags:",
+	"  --root <dir>",
+	"      A directory tool calls may read and write under (repeatable; default: the current directory).",
+	"  --author <name>",
+	"      Author of every change (default: FOLIO_AUTHOR, then git user.name). Without one, changes are refused.",
+	"  -h, --help",
+	"      Show this help.",
+	""
+].join("\n");
+const runMcp = async (rest, io) => {
+	const fail = (error) => {
+		const hint = error.hint === void 0 ? "" : `hint: ${error.hint}\n`;
+		io.stderr(`error: ${error.message}\n${hint}`);
+		return exitCodeForError(error.code);
+	};
+	const parsed = Result.try({
+		try: () => parseArgs({
+			args: [...rest],
+			options: {
+				root: {
+					type: "string",
+					multiple: true
+				},
+				author: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			},
+			strict: true
+		}),
+		catch: (error) => usageError(error instanceof Error ? error.message : String(error))
+	});
+	if (parsed.isErr()) return fail(parsed.error);
+	const { values } = parsed.value;
+	if (values.help === true) {
+		io.stdout(MCP_HELP);
+		return EXIT_CODES.ok;
+	}
+	const roots = await resolveRoots(values.root ?? [io.cwd]);
+	if (roots.isErr()) return fail(roots.error);
+	if (io.stdio === void 0) return fail(usageError("folio mcp needs stdin and stdout streams."));
+	const author = resolveAuthor({
+		explicit: values.author,
+		env: io.env,
+		cwd: io.cwd
+	});
+	if (author.isErr()) io.stderr(`folio mcp: ${author.error.message} Changes will be refused.\n`);
+	io.stderr(`folio mcp ${version}: roots ${roots.value.join(", ")}\n`);
+	await serveFolioMcp({
+		input: io.stdio.input,
+		output: io.stdio.output,
+		roots: roots.value,
+		author: author.isOk() ? author.value : void 0
+	});
+	return EXIT_CODES.ok;
+};
+/** Run `folio` with the given arguments (without the executable); resolves to the exit code. */
+const runFolioCli = async (argv, io) => {
+	const [name, ...rest] = argv;
+	if (name === void 0 || name === "help" || name === "--help" || name === "-h") {
+		io.stdout(rootHelp());
+		return EXIT_CODES.ok;
+	}
+	if (name === "--version" || name === "-V") {
+		io.stdout(`${version}\n`);
+		return EXIT_CODES.ok;
+	}
+	if (name === "mcp") return await runMcp(rest, io);
+	if (name === "render") return await runRender(rest, io);
+	if (name === "serve") return await runServe(rest, io);
+	const resolved = findCommand(name);
+	if (resolved === void 0) return emit({
+		io,
+		format: requestedFormat(rest, io),
+		tool: name,
+		result: Result.err(usageError(`Unknown command ${JSON.stringify(name)}.`, "Run folio --help."))
+	});
+	return await runCommand(resolved, rest, io);
+};
+//#endregion
+export { runFolioCli };

package/dist/document.d.ts

@@ -0,0 +1,43 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+import { FolioDocxReviewer } from "@stll/folio-core/server";
+//#region src/document.d.ts
+/** Largest `.docx` the CLI opens; larger inputs are refused before reading. */
+declare const MAX_DOCUMENT_BYTES: number;
+/** A file's version: the lowercase hex SHA-256 of its bytes. */
+declare const fileVersionOf: (bytes: Uint8Array) => string;
+declare const isFileVersion: (value: unknown) => value is string;
+/** Which file a path named when it was read: device and inode. */
+type FileIdentity = {
+  dev: number;
+  ino: number;
+};
+declare const sameFile: (left: FileIdentity, right: FileIdentity) => boolean;
+/** The bytes of one input file and the version they hash to. */
+type LoadedFile = {
+  /** Real path (symlinks resolved) the bytes were read from. */
+  path: string;
+  bytes: Uint8Array<ArrayBuffer>;
+  fileVersion: string;
+  identity: FileIdentity;
+  /** Hard links to the file; a write refuses a file with more than one. */
+  links: number;
+};
+/**
+ * `O_NOFOLLOW` where the platform has it: opening a path whose last
+ * component is a symlink fails instead of following it.
+ */
+declare const NO_FOLLOW: number;
+/** The `code` of a Node.js file-system error, when there is one. */
+declare const errnoCode: (error: unknown) => string | undefined;
+/** Read one input file, refusing directories and files over the size bound. */
+declare const readDocumentFile: (inputPath: string) => Promise<Result<LoadedFile, FolioCliError>>;
+/**
+ * Parse a loaded file into a headless reviewer. `author` is required for a
+ * reviewer that will author changes; reads pass none and never write.
+ */
+declare const openReviewer: (file: LoadedFile, author?: string) => Promise<Result<FolioDocxReviewer, FolioCliError>>;
+/** Refuse when the caller's expected version is not the file's current one. */
+declare const checkExpectedVersion: (file: LoadedFile, expected: string | undefined) => Result<void, FolioCliError>;
+//#endregion
+export { FileIdentity, LoadedFile, MAX_DOCUMENT_BYTES, NO_FOLLOW, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };

package/dist/document.js

@@ -0,0 +1,127 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { FolioDocxReviewer } from "@stll/folio-core/server";
+//#region src/document.ts
+/** Largest `.docx` the CLI opens; larger inputs are refused before reading. */
+const MAX_DOCUMENT_BYTES = 64 * 1024 * 1024;
+const FILE_VERSION_PATTERN = /^[0-9a-f]{64}$/u;
+/** A file's version: the lowercase hex SHA-256 of its bytes. */
+const fileVersionOf = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const isFileVersion = (value) => typeof value === "string" && FILE_VERSION_PATTERN.test(value);
+const sameFile = (left, right) => left.dev === right.dev && left.ino === right.ino;
+/**
+* `O_NOFOLLOW` where the platform has it: opening a path whose last
+* component is a symlink fails instead of following it.
+*/
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+/** The `code` of a Node.js file-system error, when there is one. */
+const errnoCode = (error) => {
+	if (typeof error !== "object" || error === null || !("code" in error)) return;
+	return typeof error.code === "string" ? error.code : void 0;
+};
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+const fileSystemError = (filePath, error) => errnoCode(error) === "ENOENT" ? cliError({
+	code: FOLIO_CLI_ERROR_CODES.notFound,
+	message: `No file at ${filePath}.`
+}) : cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message: `Cannot read ${filePath}: ${describeError(error)}`
+});
+/**
+* Read through one handle: the path is resolved, stat'ed, opened without
+* following a final symlink, and the handle must be the same file the stat
+* saw, so a swap between the check and the read is refused.
+*/
+const readThroughHandle = async (real) => {
+	const checked = await Result.tryPromise({
+		try: () => stat(real),
+		catch: (error) => fileSystemError(real, error)
+	});
+	if (checked.isErr()) return Result.err(checked.error);
+	if (!checked.value.isFile()) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidInput,
+		message: `${real} is not a file.`
+	}));
+	const read = await Result.tryPromise({
+		try: async () => {
+			const handle = await open(real, constants.O_RDONLY | NO_FOLLOW);
+			try {
+				const opened = await handle.stat();
+				const identity = {
+					dev: opened.dev,
+					ino: opened.ino
+				};
+				if (!opened.isFile() || !sameFile(identity, checked.value)) return "swapped";
+				if (opened.size > 67108864) return "tooLarge";
+				return {
+					bytes: new Uint8Array(await handle.readFile()),
+					identity,
+					links: opened.nlink
+				};
+			} finally {
+				await handle.close();
+			}
+		},
+		catch: (error) => fileSystemError(real, error)
+	});
+	if (read.isErr()) return Result.err(read.error);
+	if (read.value === "swapped") return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidInput,
+		message: `${real} changed while it was being opened.`,
+		hint: "Retry once nothing else is replacing the file."
+	}));
+	if (read.value === "tooLarge") return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.tooLarge,
+		message: `${real} is over the ${MAX_DOCUMENT_BYTES}-byte limit.`
+	}));
+	return Result.ok(read.value);
+};
+/** Read one input file, refusing directories and files over the size bound. */
+const readDocumentFile = async (inputPath) => {
+	const absolute = path.resolve(inputPath);
+	const real = await Result.tryPromise({
+		try: () => realpath(absolute),
+		catch: (error) => fileSystemError(absolute, error)
+	});
+	if (real.isErr()) return Result.err(real.error);
+	const opened = await readThroughHandle(real.value);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { bytes, identity, links } = opened.value;
+	return Result.ok({
+		path: real.value,
+		bytes,
+		fileVersion: fileVersionOf(bytes),
+		identity,
+		links
+	});
+};
+/**
+* Parse a loaded file into a headless reviewer. `author` is required for a
+* reviewer that will author changes; reads pass none and never write.
+*/
+const openReviewer = async (file, author) => await Result.tryPromise({
+	try: () => FolioDocxReviewer.fromBuffer(file.bytes.slice().buffer, { ...author !== void 0 && { author } }),
+	catch: (error) => cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+		message: `${file.path} is not a readable .docx package: ${describeError(error)}`
+	})
+});
+/** Refuse when the caller's expected version is not the file's current one. */
+const checkExpectedVersion = (file, expected) => {
+	if (expected === void 0 || expected === file.fileVersion) return Result.ok();
+	return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.staleVersion,
+		message: `${file.path} changed since it was read: expected version ${expected}, found ${file.fileVersion}.`,
+		hint: "Re-read the document and retry against its current fileVersion.",
+		details: {
+			expected,
+			actual: file.fileVersion
+		}
+	}));
+};
+//#endregion
+export { MAX_DOCUMENT_BYTES, NO_FOLLOW, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+//#region src/errors.d.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.
+ */
+declare const EXIT_CODES: {
+  readonly ok: 0;
+  readonly unexpected: 1;
+  readonly validation: 2;
+  readonly notFound: 6;
+  readonly permissionDenied: 8;
+  readonly conflict: 10;
+};
+type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/** Every exit code with its meaning, ordered numerically, for `--help`. */
+declare const exitCodeEntries: () => readonly {
+  code: number;
+  meaning: string;
+}[];
+/** Machine codes carried in `error.code` of a failure envelope. */
+declare const FOLIO_CLI_ERROR_CODES: {
+  readonly usage: "usage_error";
+  readonly invalidInput: "invalid_input";
+  readonly invalidDocument: "invalid_document";
+  readonly tooLarge: "too_large";
+  readonly notFound: "not_found";
+  readonly outsideRoot: "outside_root";
+  readonly unsafePath: "unsafe_path";
+  readonly invalidDestination: "invalid_destination";
+  readonly staleVersion: "stale_version";
+  readonly staleTarget: "stale_target";
+  readonly ambiguousTarget: "ambiguous_target";
+  readonly operationRejected: "operation_rejected";
+  readonly repackRequired: "repack_required";
+  readonly authorRequired: "author_required";
+  readonly locked: "locked";
+  readonly destinationExists: "destination_exists";
+  readonly transactionConflict: "transaction_conflict";
+  readonly integrityFailed: "integrity_failed";
+  readonly rendererUnavailable: "renderer_unavailable";
+  readonly internal: "internal_error";
+};
+type FolioCliErrorCode = (typeof FOLIO_CLI_ERROR_CODES)[keyof typeof FOLIO_CLI_ERROR_CODES];
+declare const exitCodeForError: (code: FolioCliErrorCode) => ExitCode;
+declare const FolioCliError_base: import("better-result").TaggedErrorClass<"FolioCliError">;
+/**
+ * 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.
+ */
+declare class FolioCliError extends FolioCliError_base<{
+  code: FolioCliErrorCode;
+  message: string;
+  hint?: string;
+  details?: unknown;
+}> {}
+type CliErrorOptions = {
+  code: FolioCliErrorCode;
+  message: string;
+  hint?: string | undefined;
+  details?: unknown;
+};
+/** Build a {@link FolioCliError} without spelling absent optional fields. */
+declare const cliError: ({ code, message, hint, details }: CliErrorOptions) => FolioCliError;
+//#endregion
+export { EXIT_CODES, ExitCode, FOLIO_CLI_ERROR_CODES, FolioCliError, FolioCliErrorCode, cliError, exitCodeEntries, exitCodeForError };