document-cli 1.0.1 → 1.2.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { OdbNoEmbeddedDataSourceError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, createLocalDocumentConverter, odbToCsv, odbToXlsx, odmToPdf, readOdbTables, readPdf } from "documents.js";
+import { OdbNoEmbeddedDataSourceError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, UnrecognizedDocumentSchemaError, buildDocxPackage, buildMarkdownText, buildOdgPackage, buildOdpPackage, buildOdsPackage, buildOdtPackage, buildPptxPackage, createLocalDocumentConverter, documentFromJson, documentPackageWithSchema, encodeMarkdownText, encodePackage, odbToCsv, odbToXlsx, odmToPdf, readOdbForms, readOdbReports, readOdbTables, readPdf, writePdf } from "documents.js";
 import { basename, dirname, extname, join } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
-import { decodePackage } from "odf.js";
+import { decodePackage, encodePackage as encodePackage$1 } from "odf.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/format.ts
 const EXTENSION_TO_FORMAT = {
@@ -14,6 +14,8 @@ const EXTENSION_TO_FORMAT = {
 	ods: "ods",
 	odg: "odg",
 	odf: "odf",
+	markdown: "markdown",
+	md: "markdown",
 	pdf: "pdf"
 };
 const FORMAT_TO_EXTENSION = {
@@ -25,6 +27,7 @@ const FORMAT_TO_EXTENSION = {
 	ods: "ods",
 	odg: "odg",
 	odf: "odf",
+	markdown: "md",
 	pdf: "pdf"
 };
 function isDocumentFormat(value) {
@@ -108,6 +111,22 @@ function createDiagnosticReporter(options) {
 		}
 	};
 }
+function createFontSubstitutionReporter(options) {
+	const { json, quiet, command } = options;
+	return (substitution) => {
+		if (quiet) return;
+		if (json) {
+			process.stderr.write(`${JSON.stringify({
+				type: "font-substitution",
+				command,
+				...substitution
+			})}\n`);
+			return;
+		}
+		const styleClause = `${substitution.requestedBold ? " bold" : ""}${substitution.requestedItalic ? " italic" : ""}`;
+		process.stderr.write(`[${command}] font substitution: "${substitution.requestedFamily}"${styleClause} -> "${substitution.resolvedFamily}" (${substitution.reason})\n`);
+	};
+}
 function substitutionToDiagnostic(substitution, pageIndex) {
 	return {
 		severity: "warning",
@@ -116,6 +135,13 @@ function substitutionToDiagnostic(substitution, pageIndex) {
 		pageIndex
 	};
 }
+function fontSubstitutionToDiagnostic(substitution) {
+	return {
+		severity: "info",
+		code: "font/substituted",
+		message: `"${`${substitution.requestedFamily}${substitution.requestedBold ? " bold" : ""}${substitution.requestedItalic ? " italic" : ""}`}" is not available; ${substitution.reason === "vendored-substitute" ? `substituted the metric-compatible "${substitution.resolvedFamily}"` : `substituted another face of "${substitution.resolvedFamily}"`}`
+	};
+}
 function pdfDiagnosticToDiagnostic(diagnostic) {
 	return {
 		severity: diagnostic.severity,
@@ -140,6 +166,172 @@ function mapErrorToExit(error, abortReason) {
 	return 1;
 }
 //#endregion
+//#region src/runtime/font-face.ts
+var FontFaceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FontFaceError";
+	}
+};
+const SFNT_VERSION_TRUETYPE = 65536;
+const SFNT_VERSION_CFF = 1330926671;
+const SFNT_VERSION_APPLE_TRUE = 1953658213;
+const SFNT_VERSION_APPLE_TYP1 = 1954115633;
+const SFNT_VERSION_COLLECTION = 1953784678;
+const SFNT_VERSIONS = /* @__PURE__ */ new Set([
+	SFNT_VERSION_TRUETYPE,
+	SFNT_VERSION_CFF,
+	SFNT_VERSION_APPLE_TRUE,
+	SFNT_VERSION_APPLE_TYP1
+]);
+const TABLE_DIRECTORY_HEADER_SIZE = 12;
+const TABLE_RECORD_SIZE = 16;
+const TABLE_TAG_SIZE = 4;
+const NAME_HEADER_SIZE = 6;
+const NAME_RECORD_SIZE = 12;
+const NAME_ID_FAMILY = 1;
+const NAME_ID_TYPOGRAPHIC_FAMILY = 16;
+const PLATFORM_UNICODE = 0;
+const PLATFORM_MACINTOSH = 1;
+const PLATFORM_WINDOWS = 3;
+const MACINTOSH_ENCODING_ROMAN = 0;
+const OS2_FS_SELECTION_OFFSET = 62;
+const OS2_MINIMUM_SIZE = 64;
+const OS2_FS_SELECTION_ITALIC = 1;
+const OS2_FS_SELECTION_BOLD = 32;
+const HEAD_MAC_STYLE_OFFSET = 44;
+const HEAD_MINIMUM_SIZE = 46;
+const HEAD_MAC_STYLE_BOLD = 1;
+const HEAD_MAC_STYLE_ITALIC = 2;
+function viewOf(bytes) {
+	return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function decodeTag(view, offset) {
+	let tag = "";
+	for (let i = 0; i < TABLE_TAG_SIZE; i++) tag += String.fromCharCode(view.getUint8(offset + i));
+	return tag;
+}
+function decodeUtf16Be(view, offset, length) {
+	let text = "";
+	for (let i = 0; i + 1 < length; i += 2) text += String.fromCharCode(view.getUint16(offset + i));
+	return text;
+}
+function decodeMacintoshAscii(view, offset, length) {
+	let text = "";
+	for (let i = 0; i < length; i++) {
+		const byte = view.getUint8(offset + i);
+		if (byte > 126) return;
+		text += String.fromCharCode(byte);
+	}
+	return text;
+}
+function readTableDirectory(view, source) {
+	if (view.byteLength < TABLE_DIRECTORY_HEADER_SIZE) throw new FontFaceError(`${source} is too short to be a font file (${String(view.byteLength)} bytes)`);
+	const sfntVersion = view.getUint32(0);
+	if (sfntVersion === SFNT_VERSION_COLLECTION) throw new FontFaceError(`${source} is a TrueType Collection (.ttc), which packs several faces into one file; extract the single face you want and pass that instead`);
+	if (!SFNT_VERSIONS.has(sfntVersion)) throw new FontFaceError(`${source} is not a TrueType/OpenType font file (no recognised sfnt version); a .woff/.woff2 file must be converted to .ttf/.otf first`);
+	const numTables = view.getUint16(4);
+	if (view.byteLength < TABLE_DIRECTORY_HEADER_SIZE + numTables * TABLE_RECORD_SIZE) throw new FontFaceError(`${source} declares ${String(numTables)} tables but is too short to hold that many table records`);
+	const tables = /* @__PURE__ */ new Map();
+	for (let i = 0; i < numTables; i++) {
+		const recordOffset = TABLE_DIRECTORY_HEADER_SIZE + i * TABLE_RECORD_SIZE;
+		const tag = decodeTag(view, recordOffset);
+		const offset = view.getUint32(recordOffset + 8);
+		const length = view.getUint32(recordOffset + 12);
+		if (offset + length > view.byteLength || tables.has(tag)) continue;
+		tables.set(tag, {
+			offset,
+			length
+		});
+	}
+	return tables;
+}
+function tableView(bytes, table) {
+	return new DataView(bytes.buffer, bytes.byteOffset + table.offset, table.length);
+}
+function readNameRecords(name) {
+	if (name.byteLength < NAME_HEADER_SIZE) return [];
+	const count = name.getUint16(2);
+	const storageOffset = name.getUint16(4);
+	if (name.byteLength < NAME_HEADER_SIZE + count * NAME_RECORD_SIZE) return [];
+	const records = [];
+	for (let i = 0; i < count; i++) {
+		const recordOffset = NAME_HEADER_SIZE + i * NAME_RECORD_SIZE;
+		records.push({
+			platformId: name.getUint16(recordOffset),
+			encodingId: name.getUint16(recordOffset + 2),
+			nameId: name.getUint16(recordOffset + 6),
+			length: name.getUint16(recordOffset + 8),
+			stringOffset: storageOffset + name.getUint16(recordOffset + 10)
+		});
+	}
+	return records;
+}
+function platformPreference(record) {
+	if (record.platformId === PLATFORM_WINDOWS) return 0;
+	if (record.platformId === PLATFORM_UNICODE) return 1;
+	if (record.platformId === PLATFORM_MACINTOSH && record.encodingId === MACINTOSH_ENCODING_ROMAN) return 2;
+	return Number.POSITIVE_INFINITY;
+}
+function readNameString(name, records, nameId) {
+	const candidates = records.filter((record) => record.nameId === nameId && Number.isFinite(platformPreference(record))).sort((left, right) => platformPreference(left) - platformPreference(right));
+	for (const record of candidates) {
+		if (record.stringOffset + record.length > name.byteLength) continue;
+		const text = record.platformId === PLATFORM_MACINTOSH ? decodeMacintoshAscii(name, record.stringOffset, record.length) : decodeUtf16Be(name, record.stringOffset, record.length);
+		if (text !== void 0 && text.length > 0) return text;
+	}
+}
+function readStyleBits(bytes, tables, source) {
+	const os2 = tables.get("OS/2");
+	if (os2 !== void 0 && os2.length >= OS2_MINIMUM_SIZE) {
+		const fsSelection = tableView(bytes, os2).getUint16(OS2_FS_SELECTION_OFFSET);
+		return {
+			bold: (fsSelection & OS2_FS_SELECTION_BOLD) !== 0,
+			italic: (fsSelection & OS2_FS_SELECTION_ITALIC) !== 0
+		};
+	}
+	const head = tables.get("head");
+	if (head !== void 0 && head.length >= HEAD_MINIMUM_SIZE) {
+		const macStyle = tableView(bytes, head).getUint16(HEAD_MAC_STYLE_OFFSET);
+		return {
+			bold: (macStyle & HEAD_MAC_STYLE_BOLD) !== 0,
+			italic: (macStyle & HEAD_MAC_STYLE_ITALIC) !== 0
+		};
+	}
+	throw new FontFaceError(`${source} declares neither a readable 'OS/2' nor a readable 'head' table, so its weight and slope cannot be determined`);
+}
+function describeFontFace(bytes, source) {
+	const tables = readTableDirectory(viewOf(bytes), source);
+	const nameTable = tables.get("name");
+	if (nameTable === void 0) throw new FontFaceError(`${source} declares no 'name' table, so the font family it provides cannot be determined`);
+	const name = tableView(bytes, nameTable);
+	const records = readNameRecords(name);
+	const family = readNameString(name, records, NAME_ID_TYPOGRAPHIC_FAMILY) ?? readNameString(name, records, NAME_ID_FAMILY);
+	if (family === void 0) throw new FontFaceError(`${source} declares no family name in its 'name' table, so the font family it provides cannot be determined`);
+	const { bold, italic } = readStyleBits(bytes, tables, source);
+	return {
+		family,
+		bold,
+		italic
+	};
+}
+//#endregion
+//#region src/runtime/fonts.ts
+async function loadProvidedFonts(paths, options) {
+	const fonts = [];
+	for (const path of paths) {
+		const bytes = new Uint8Array(await readFile(path, { signal: options?.signal }));
+		const face = describeFontFace(bytes, path);
+		fonts.push({
+			family: face.family,
+			bold: face.bold,
+			italic: face.italic,
+			bytes
+		});
+	}
+	return fonts;
+}
+//#endregion
 //#region src/runtime/io.ts
 function isUint8Array(value) {
 	return value instanceof Uint8Array;
@@ -180,6 +372,18 @@ function resolveDefaultOutputPath(inputPath, targetFormat) {
 }
 //#endregion
 //#region src/commands/shared.ts
+const KNOWN_DOCUMENT_FORMATS = "docx, pptx, xlsx, odt, odp, ods, odg, odf, markdown, pdf";
+function resolveTargetFormat(output, out, to) {
+	if (to !== void 0) {
+		if (!isDocumentFormat(to)) return { errorMessage: `unknown --to format '${to}'; expected one of ${KNOWN_DOCUMENT_FORMATS}` };
+		return { format: to };
+	}
+	const destination = output ?? out;
+	if (destination === void 0) return { errorMessage: "cannot infer a target format -- pass an output path with a recognised extension, --out with one, or --to <format>" };
+	const inferred = inferFormatFromExtension(destination);
+	if (inferred === void 0) return { errorMessage: `cannot infer a target format from '${destination}'; pass --to <format> instead` };
+	return { format: inferred };
+}
 function formatError(error, verbose) {
 	if (!(error instanceof Error)) return `error: ${String(error)}`;
 	const stackClause = verbose && error.stack !== void 0 ? `\n${error.stack}` : "";
@@ -196,13 +400,22 @@ function buildConversionAction(source, target) {
 		const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeoutMs });
 		try {
 			const inputBytes = await readInput(input, { signal });
+			const fonts = await loadProvidedFonts(options.fontFiles ?? [], { signal });
 			const result = await createLocalDocumentConverter().convert({
 				source: {
 					format: source,
 					bytes: new Uint8Array(inputBytes)
 				},
 				targetFormat: target
-			}, { signal });
+			}, {
+				signal,
+				fonts,
+				onFontSubstitution: options.reportFontSubstitutions === true ? createFontSubstitutionReporter({
+					json: options.json,
+					quiet: options.quiet,
+					command
+				}) : void 0
+			});
 			await writeOutput(resolvedOutput, result.document.bytes);
 			const reporter = createDiagnosticReporter({
 				json: options.json,
@@ -211,7 +424,7 @@ function buildConversionAction(source, target) {
 			});
 			for (const diagnostic of result.diagnostics) reporter.report(diagnostic);
 			if (options.dumpPackage !== void 0) if (result.package === void 0) process.stderr.write(`[${command}] this conversion does not produce an intermediate DocumentPackage\n`);
-			else await writeFile(options.dumpPackage, JSON.stringify(result.package, void 0, 2));
+			else await writeFile(options.dumpPackage, JSON.stringify(documentPackageWithSchema(result.package), void 0, 2));
 			reporter.summarize({
 				output: resolvedOutput,
 				bytes: result.document.bytes.byteLength,
@@ -244,6 +457,14 @@ function addVerboseOption(command) {
 function addDumpPackageOption(command) {
 	return command.option("--dump-package <file>", "write the intermediate DocumentPackage (content + layout) this conversion built to a JSON file");
 }
+function collectFontFile(value, previous) {
+	return [...previous, value];
+}
+function addFontOptions(command) {
+	command.option("--font-file <path>", "embed this font file (.ttf/.otf) when the document asks for the family it declares; repeatable. The family, weight, and slope are read from the font's own 'name'/'OS/2' tables, so no accompanying family flag is needed", collectFontFile, []);
+	command.option("--report-font-substitutions", "print each font face that resolved to something other than what the document asked for to stderr, as it happens", false);
+	return command;
+}
 function addConversionFlags(command) {
 	addOutOption(command);
 	addTimeoutOption(command);
@@ -261,21 +482,11 @@ function toConversionCommandOptions(options) {
 		json: options.json,
 		quiet: options.quiet,
 		verbose: options.verbose,
-		dumpPackage: options.dumpPackage
+		dumpPackage: options.dumpPackage,
+		fontFiles: options.fontFile,
+		reportFontSubstitutions: options.reportFontSubstitutions
 	};
 }
-const KNOWN_FORMATS = "docx, pptx, xlsx, odt, odp, ods, odg, odf, pdf";
-function resolveGenericTarget(output, options) {
-	if (options.to !== void 0) {
-		if (!isDocumentFormat(options.to)) return { errorMessage: `unknown --to format '${options.to}'; expected one of ${KNOWN_FORMATS}` };
-		return { format: options.to };
-	}
-	const destination = output ?? options.out;
-	if (destination === void 0) return { errorMessage: "cannot infer a target format -- pass an output path with a recognised extension, --out with one, or --to <format>" };
-	const inferred = inferFormatFromExtension(destination);
-	if (inferred === void 0) return { errorMessage: `cannot infer a target format from '${destination}'; pass --to <format> instead` };
-	return { format: inferred };
-}
 async function runGenericConvert(input, output, options) {
 	const extension = extname(input).toLowerCase();
 	if (extension === ".odm") {
@@ -288,10 +499,10 @@ async function runGenericConvert(input, output, options) {
 	}
 	const source = inferFormatFromExtension(input);
 	if (source === void 0) {
-		process.stderr.write(`convert: cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_FORMATS}) or use one of the explicit '<source>-to-<target>' commands\n`);
+		process.stderr.write(`convert: cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_DOCUMENT_FORMATS}) or use one of the explicit '<source>-to-<target>' commands\n`);
 		return 2;
 	}
-	const target = resolveGenericTarget(output, options);
+	const target = resolveTargetFormat(output, options.out, options.to);
 	if ("errorMessage" in target) {
 		process.stderr.write(`convert: ${target.errorMessage}\n`);
 		return 2;
@@ -305,6 +516,7 @@ function registerConversionCommands(program) {
 		const command = program.command(`${commandName} <input> [output]`).description(`convert a ${source} document to ${target}`);
 		addConversionFlags(command);
 		addDumpPackageOption(command);
+		if (target === "pdf") addFontOptions(command);
 		command.action(async (input, output, options) => {
 			process.exitCode = await buildConversionAction(source, target)(input, output, toConversionCommandOptions(options));
 		});
@@ -312,14 +524,15 @@ function registerConversionCommands(program) {
 	const generic = program.command("convert <input> [output]").description("convert between any two supported document formats, inferring source/target from file extensions where possible");
 	addConversionFlags(generic);
 	addDumpPackageOption(generic);
-	generic.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_FORMATS})`);
+	addFontOptions(generic);
+	generic.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_DOCUMENT_FORMATS})`);
 	generic.action(async (input, output, options) => {
 		process.exitCode = await runGenericConvert(input, output, options);
 	});
 }
 //#endregion
 //#region src/commands/formats.ts
-const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, pdf-inspect";
+const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, pdf-inspect, from-package";
 function registerFormatsCommand(program) {
 	program.command("formats").description("list every source -> target conversion this CLI supports via a <source>-to-<target> command").option("--json", "emit the conversion list as a JSON array instead of a human-readable table", false).action((options) => {
 		const { conversions } = createLocalDocumentConverter();
@@ -332,6 +545,218 @@ function registerFormatsCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/from-package.ts
+function buildBytesForTarget(pkg, target) {
+	if (target === "pdf") {
+		if (pkg.layout === void 0) throw new Error("this DocumentPackage has no layout -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries one; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		return writePdf(pkg.layout);
+	}
+	switch (target) {
+		case "docx": return encodePackage(buildDocxPackage(pkg.content));
+		case "pptx": return encodePackage(buildPptxPackage(pkg.content));
+		case "odt": return encodePackage$1(buildOdtPackage(pkg.content));
+		case "odp": return encodePackage$1(buildOdpPackage(pkg.content));
+		case "ods": return encodePackage$1(buildOdsPackage(pkg.content));
+		case "odg": return encodePackage$1(buildOdgPackage(pkg.content));
+		case "markdown": return encodeMarkdownText(buildMarkdownText(pkg.content));
+		case "xlsx": throw new Error("'xlsx' cannot be built from a DocumentPackage directly -- documents.js does not re-export a ContentDocument-to-xlsx builder; convert to 'ods' here, then run 'ods-to-xlsx' on the result instead");
+		case "odf": throw new Error("'odf' (a standalone formula document) cannot be built from a DocumentPackage -- there is no ContentDocument-to-odf builder");
+	}
+}
+async function runFromPackage(input, output, options) {
+	const command = "from-package";
+	if (output !== void 0 && options.out !== void 0 && output !== options.out) {
+		process.stderr.write(`[${command}] conflicting output destinations: positional '${output}' and --out '${options.out}'\n`);
+		return 2;
+	}
+	const target = resolveTargetFormat(output, options.out, options.to);
+	if ("errorMessage" in target) {
+		process.stderr.write(`[${command}] ${target.errorMessage}\n`);
+		return 2;
+	}
+	const resolvedOutput = output ?? options.out ?? (input === "-" ? "-" : resolveDefaultOutputPath(input, target.format));
+	const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeout });
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(inputBytes);
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			process.stderr.write(`[${command}] '${input}' is not valid JSON: ${error instanceof Error ? error.message : String(error)}\n`);
+			return 1;
+		}
+		const result = documentFromJson(parsed);
+		if (result.kind !== "DocumentPackage") {
+			process.stderr.write(`[${command}] '${input}' is a ${result.kind}, not a DocumentPackage -- only a file written by --dump-package can be read back by this command\n`);
+			return 2;
+		}
+		const bytes = buildBytesForTarget(result.value, target.format);
+		await writeOutput(resolvedOutput, bytes);
+		createDiagnosticReporter({
+			json: options.json,
+			quiet: options.quiet,
+			command
+		}).summarize({
+			output: resolvedOutput,
+			bytes: bytes.byteLength,
+			diagnosticCount: 0
+		});
+		return 0;
+	} catch (error) {
+		if (error instanceof UnrecognizedDocumentSchemaError) {
+			process.stderr.write(`[${command}] '${input}' has no recognised $schema -- only a file written by --dump-package can be read back by this command\n`);
+			return 1;
+		}
+		process.stderr.write(`${formatError(error, options.verbose)}\n`);
+		return mapErrorToExit(error, getAbortReason());
+	}
+}
+function registerFromPackageCommand(program) {
+	const command = program.command("from-package <input> [output]").description("read a DocumentPackage previously written by --dump-package and export it to a real target format");
+	addOutOption(command);
+	addTimeoutOption(command);
+	addJsonOption(command);
+	addQuietOption(command);
+	addVerboseOption(command);
+	command.option("--to <format>", `target format when it cannot be inferred from the output path (${KNOWN_DOCUMENT_FORMATS})`);
+	command.action(async (input, output, options) => {
+		process.exitCode = await runFromPackage(input, output, options);
+	});
+}
+//#endregion
+//#region src/odb-structure.ts
+const INDENT = "  ";
+function indent(depth) {
+	return INDENT.repeat(depth);
+}
+function quoted(value) {
+	return `"${value}"`;
+}
+function describeDataSource(command, commandType) {
+	if (command === void 0) return commandType;
+	return commandType === void 0 ? quoted(command) : `${commandType} ${quoted(command)}`;
+}
+function countOdbFormControls(controls) {
+	return controls.reduce((total, control) => total + 1 + countOdbFormControls(control.controls), 0);
+}
+function countOdbFormDefinitionControls(definition) {
+	return countOdbFormControls(definition.controls) + definition.subForms.reduce((total, subForm) => total + countOdbFormDefinitionControls(subForm), 0);
+}
+function countOdbFormBoundControls(controls) {
+	return controls.reduce((total, control) => total + (control.dataField === void 0 ? 0 : 1) + countOdbFormBoundControls(control.controls), 0);
+}
+function countOdbFormDefinitionBoundControls(definition) {
+	return countOdbFormBoundControls(definition.controls) + definition.subForms.reduce((total, subForm) => total + countOdbFormDefinitionBoundControls(subForm), 0);
+}
+function describeOdbForm(form) {
+	const controlCount = form.forms.reduce((total, definition) => total + countOdbFormDefinitionControls(definition), 0);
+	const boundCount = form.forms.reduce((total, definition) => total + countOdbFormDefinitionBoundControls(definition), 0);
+	return `${form.name} [${form.href}] -- ${form.forms.length} form${form.forms.length === 1 ? "" : "s"}, ${controlCount} control${controlCount === 1 ? "" : "s"} (${boundCount} bound)`;
+}
+function formControlLines(control, depth) {
+	const parts = [control.tag];
+	if (control.name !== void 0) parts.push(control.name);
+	if (control.dataField !== void 0) parts.push(`-> ${control.dataField}`);
+	if (control.label !== void 0) parts.push(`label ${quoted(control.label)}`);
+	if (control.controlImplementation !== void 0) parts.push(`(${control.controlImplementation})`);
+	const nested = control.controls.flatMap((child) => formControlLines(child, depth + 1));
+	return [`${indent(depth)}${parts.join(" ")}`, ...nested];
+}
+function formDefinitionLines(definition, depth, kindLabel) {
+	const headerParts = [kindLabel];
+	if (definition.name !== void 0) headerParts.push(definition.name);
+	const dataSource = describeDataSource(definition.command, definition.commandType);
+	if (dataSource !== void 0) headerParts.push(`on ${dataSource}`);
+	const lines = [`${indent(depth)}${headerParts.join(" ")}`];
+	if (definition.datasource !== void 0) lines.push(`${indent(depth + 1)}datasource: ${definition.datasource}`);
+	if (definition.filter !== void 0) lines.push(`${indent(depth + 1)}filter: ${definition.filter}`);
+	if (definition.order !== void 0) lines.push(`${indent(depth + 1)}order: ${definition.order}`);
+	if (definition.controls.length === 0) lines.push(`${indent(depth + 1)}(no controls)`);
+	for (const control of definition.controls) lines.push(...formControlLines(control, depth + 1));
+	for (const subForm of definition.subForms) lines.push(...formDefinitionLines(subForm, depth + 1, "subform"));
+	return lines;
+}
+function formatOdbFormLines(form) {
+	if (form.forms.length === 0) return ["(this form document declares no form:form definitions)"];
+	return form.forms.flatMap((definition) => formDefinitionLines(definition, 0, "form"));
+}
+function odbFormSummary(form) {
+	return {
+		name: form.name,
+		href: form.href,
+		forms: form.forms
+	};
+}
+function countReportBandElements(band) {
+	return band?.elements.length ?? 0;
+}
+function countReportGroupElements(group) {
+	return countReportBandElements(group.header) + countReportBandElements(group.footer) + group.groups.reduce((total, nested) => total + countReportGroupElements(nested), 0);
+}
+function countReportGroups(groups) {
+	return groups.reduce((total, group) => total + 1 + countReportGroups(group.groups), 0);
+}
+function describeOdbReport(report) {
+	const dataSource = describeDataSource(report.command, report.commandType);
+	const groupCount = countReportGroups(report.groups);
+	const elementCount = countReportBandElements(report.reportHeader) + countReportBandElements(report.pageHeader) + countReportBandElements(report.detail) + countReportBandElements(report.pageFooter) + countReportBandElements(report.reportFooter) + report.groups.reduce((total, group) => total + countReportGroupElements(group), 0);
+	const source = dataSource === void 0 ? "no data source" : `on ${dataSource}`;
+	return `${report.name} [${report.href}] -- ${source}, ${groupCount} group${groupCount === 1 ? "" : "s"}, ${elementCount} element${elementCount === 1 ? "" : "s"}`;
+}
+function reportElementLine(element, depth) {
+	const parts = [element.tag];
+	if (element.name !== void 0) parts.push(quoted(element.name));
+	if (element.formula !== void 0) parts.push(`= ${element.formula}`);
+	if (element.dataField !== void 0) parts.push(`-> ${element.dataField}`);
+	const head = `${indent(depth)}${parts.join(" ")}`;
+	return element.text === void 0 ? head : `${head}: ${quoted(element.text)}`;
+}
+function reportBandLines(band, depth) {
+	if (band === void 0) return [];
+	const header = band.name === void 0 ? band.kind : `${band.kind} ${quoted(band.name)}`;
+	const lines = [`${indent(depth)}${header}`];
+	if (band.elements.length === 0) lines.push(`${indent(depth + 1)}(no elements)`);
+	for (const element of band.elements) lines.push(reportElementLine(element, depth + 1));
+	return lines;
+}
+function reportFunctionLines(functions, depth) {
+	if (functions.length === 0) return [];
+	return [`${indent(depth)}functions`, ...functions.map((fn) => `${indent(depth + 1)}${fn.name} = ${fn.formula}`)];
+}
+function reportGroupLines(group, depth) {
+	const headerParts = ["group"];
+	if (group.groupExpression !== void 0) headerParts.push(group.groupExpression);
+	const attributes = [];
+	if (group.sortExpression !== void 0) attributes.push(`sort ${group.sortExpression} ${group.sortAscending === false ? "descending" : "ascending"}`);
+	if (group.startNewColumn === true) attributes.push("new column");
+	if (group.resetPageNumber === true) attributes.push("reset page number");
+	if (group.keepTogether !== void 0) attributes.push(`keep together ${group.keepTogether}`);
+	if (attributes.length > 0) headerParts.push(`(${attributes.join(", ")})`);
+	return [
+		`${indent(depth)}${headerParts.join(" ")}`,
+		...reportBandLines(group.header, depth + 1),
+		...group.groups.flatMap((nested) => reportGroupLines(nested, depth + 1)),
+		...reportFunctionLines(group.functions, depth + 1),
+		...reportBandLines(group.footer, depth + 1)
+	];
+}
+function formatOdbReportLines(report) {
+	const lines = [];
+	const dataSource = describeDataSource(report.command, report.commandType);
+	if (dataSource !== void 0) lines.push(`data source: ${dataSource}`);
+	if (report.caption !== void 0) lines.push(`caption: ${report.caption}`);
+	if (report.mimeType !== void 0) lines.push(`mime type: ${report.mimeType}`);
+	lines.push(...reportBandLines(report.reportHeader, 0));
+	lines.push(...reportBandLines(report.pageHeader, 0));
+	lines.push(...report.groups.flatMap((group) => reportGroupLines(group, 0)));
+	lines.push(...reportBandLines(report.detail, 0));
+	lines.push(...reportBandLines(report.pageFooter, 0));
+	lines.push(...reportBandLines(report.reportFooter, 0));
+	lines.push(...reportFunctionLines(report.functions, 0));
+	return lines;
+}
+//#endregion
 //#region src/commands/odb.ts
 function reportOdbError(command, error, verbose, abortReason) {
 	if (error instanceof OdbNoEmbeddedDataSourceError || error instanceof OdbUnsupportedFormatError) {
@@ -433,6 +858,52 @@ async function runOdbTables(input, options) {
 		return reportOdbError(command, error, false, getAbortReason());
 	}
 }
+async function runOdbForms(input, options) {
+	const command = "odb-forms";
+	const { signal, getAbortReason } = createRuntimeSignal({});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const forms = readOdbForms(decodePackage(new Uint8Array(inputBytes)));
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(forms.map((form) => odbFormSummary(form)))}\n`);
+			return 0;
+		}
+		if (forms.length === 0) {
+			process.stdout.write("This database declares no forms.\n");
+			return 0;
+		}
+		for (const form of forms) {
+			process.stdout.write(`${describeOdbForm(form)}\n`);
+			for (const line of formatOdbFormLines(form)) process.stdout.write(`  ${line}\n`);
+		}
+		return 0;
+	} catch (error) {
+		return reportOdbError(command, error, false, getAbortReason());
+	}
+}
+async function runOdbReports(input, options) {
+	const command = "odb-reports";
+	const { signal, getAbortReason } = createRuntimeSignal({});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const reports = readOdbReports(decodePackage(new Uint8Array(inputBytes)));
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(reports)}\n`);
+			return 0;
+		}
+		if (reports.length === 0) {
+			process.stdout.write("This database declares no reports.\n");
+			return 0;
+		}
+		for (const report of reports) {
+			process.stdout.write(`${describeOdbReport(report)}\n`);
+			for (const line of formatOdbReportLines(report)) process.stdout.write(`  ${line}\n`);
+		}
+		return 0;
+	} catch (error) {
+		return reportOdbError(command, error, false, getAbortReason());
+	}
+}
 function registerOdbToXlsxCommand(program) {
 	const command = program.command("odb-to-xlsx <input> [output]").description("extract every table an embedded .odb database declares into one xlsx workbook, one sheet per table");
 	addOutOption(command);
@@ -461,10 +932,22 @@ function registerOdbTablesCommand(program) {
 		process.exitCode = await runOdbTables(input, options);
 	});
 }
+function registerOdbFormsCommand(program) {
+	program.command("odb-forms <input>").description("list every form an .odb declares, with each form's own data source and its field-bound controls").option("--json", "emit the form structure as a JSON array instead of a human-readable report", false).action(async (input, options) => {
+		process.exitCode = await runOdbForms(input, options);
+	});
+}
+function registerOdbReportsCommand(program) {
+	program.command("odb-reports <input>").description("list every report an .odb declares, with each report's own data-source command, band/group structure, and rpt: formula expressions").option("--json", "emit the report structure as a JSON array instead of a human-readable report", false).action(async (input, options) => {
+		process.exitCode = await runOdbReports(input, options);
+	});
+}
 function registerOdbCommands(program) {
 	registerOdbToXlsxCommand(program);
 	registerOdbToCsvCommand(program);
 	registerOdbTablesCommand(program);
+	registerOdbFormsCommand(program);
+	registerOdbReportsCommand(program);
 }
 //#endregion
 //#region src/commands/odm.ts
@@ -500,11 +983,26 @@ async function runOdmToPdf(input, output, options) {
 		command
 	});
 	let diagnosticCount = 0;
+	const reportFontSubstitution = options.reportFontSubstitutions === true ? createFontSubstitutionReporter({
+		json: options.json,
+		quiet: options.quiet,
+		command
+	}) : void 0;
 	try {
 		const inputBytes = await readInput(input, { signal });
+		const fonts = await loadProvidedFonts(options.fontFile ?? [], { signal });
 		const bytes = odmToPdf(new Uint8Array(inputBytes), {
 			signal,
 			resolveSubDocument,
+			fonts,
+			onFontSubstitution: (substitution) => {
+				if (reportFontSubstitution !== void 0) {
+					reportFontSubstitution(substitution);
+					return;
+				}
+				diagnosticCount += 1;
+				reporter.report(fontSubstitutionToDiagnostic(substitution));
+			},
 			onSubstitution: (substitution, context) => {
 				diagnosticCount += 1;
 				reporter.report(substitutionToDiagnostic(substitution, context.pageIndex));
@@ -533,6 +1031,7 @@ function registerOdmCommand(program) {
 	addJsonOption(command);
 	addQuietOption(command);
 	addVerboseOption(command);
+	addFontOptions(command);
 	command.option("--chapters-dir <dir>", "directory to search for each unresolved chapter href, matched by the href's own basename");
 	command.option("--chapter <href>=<file>", "resolve one chapter href to a local file explicitly; repeatable", collectChapterOverride, /* @__PURE__ */ new Map());
 	command.action(async (input, output, options) => {
@@ -629,7 +1128,7 @@ function registerPdfInspectCommand(program) {
 }
 //#endregion
 //#region package.json
-var version = "1.0.1";
+var version = "1.2.0";
 //#endregion
 //#region src/program.ts
 function createProgram() {
@@ -642,6 +1141,7 @@ function createProgram() {
 	});
 	registerConversionCommands(program);
 	registerFormatsCommand(program);
+	registerFromPackageCommand(program);
 	registerOdmCommand(program);
 	registerOdbCommands(program);
 	registerPdfInspectCommand(program);