@stll/folio-cli 0.3.0 → 0.3.2

package/dist/document.d.ts

@@ -16,7 +16,12 @@ type LoadedFile = {
   /** Hard links to the file; a write refuses a file with more than one. */
   links: number;
 };
-/** Read one input file, refusing directories and files over the size bound. */
+/**
+ * Read one input file, refusing directories, files over the size bound, and
+ * anything that is not a WordprocessingML package. Every command and tool
+ * that takes a document reads it here, so none can treat an archive without
+ * a main document part as an empty document.
+ */
 declare const readDocumentFile: (inputPath: string) => Promise<Result<LoadedFile, FolioCliError>>;
 /**
  * Parse a loaded file into a headless reviewer. `author` is required for a

package/dist/document.js

@@ -1,5 +1,6 @@
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
 import { NO_FOLLOW, errnoCode, fileVersionOf, sameFile } from "./file-system.js";
+import { checkWordprocessingPackage } from "./main-document-part.js";
 import { Result } from "better-result";
 import { constants } from "node:fs";
 import { open, realpath, stat } from "node:fs/promises";
@@ -67,7 +68,12 @@ const readThroughHandle = async (real) => {
 	}));
 	return Result.ok(read.value);
 };
-/** Read one input file, refusing directories and files over the size bound. */
+/**
+* Read one input file, refusing directories, files over the size bound, and
+* anything that is not a WordprocessingML package. Every command and tool
+* that takes a document reads it here, so none can treat an archive without
+* a main document part as an empty document.
+*/
 const readDocumentFile = async (inputPath) => {
 	const absolute = path.resolve(inputPath);
 	const real = await Result.tryPromise({
@@ -78,6 +84,8 @@ const readDocumentFile = async (inputPath) => {
 	const opened = await readThroughHandle(real.value);
 	if (opened.isErr()) return Result.err(opened.error);
 	const { bytes, identity, links } = opened.value;
+	const checked = await checkWordprocessingPackage(real.value, bytes);
+	if (checked.isErr()) return Result.err(checked.error);
 	return Result.ok({
 		path: real.value,
 		bytes,

package/dist/editor-lease.d.ts

@@ -1,5 +1,5 @@
+import { AcquiredLease, PublicLockHolder } from "./lock.js";
 import { FolioCliError } from "./errors.js";
-import { AcquiredLease, LockHolder } from "./lock.js";
 import { Result } from "better-result";
 //#region src/editor-lease.d.ts
 /** How long an editor's lease lasts without renewal. */
@@ -24,6 +24,10 @@ type FlushRequest = {
   /** After this the writer has stopped waiting; the request is void. */
   deadline: string;
 };
+/** Request metadata safe to include in a refused editor lease response. */
+type PublicFlushRequest = Omit<FlushRequest, "leaseToken"> & {
+  leaseToken?: never;
+};
 declare const flushRequestPathFor: (documentPath: string, id: string) => string;
 /**
  * The flush requests beside `documentPath` whose writer is still waiting.
@@ -39,13 +43,13 @@ type FlushOutcome =
 /** The holder released within the wait; `versionBefore` is the file's version when asked. */
 {
   type: "flushed";
-  holder: LockHolder;
+  holder: PublicLockHolder;
   versionBefore: string | null;
 } |
 /** The holder never released; the lease was taken by the ordinary rules (stale, or `force`). */
 {
   type: "timedOut";
-  holder: LockHolder;
+  holder: PublicLockHolder;
 };
 type LeaseForWrite = {
   lease: AcquiredLease;
@@ -111,4 +115,4 @@ type WatchFlushRequestsOptions = {
  */
 declare const watchFlushRequests: ({ documentPath, token, onRequest, pollMs }: WatchFlushRequestsOptions) => FlushWatcher;
 //#endregion
-export { DEFAULT_FLUSH_WAIT_MS, EDITOR_LEASE_MS, EDITOR_RENEW_MS, FLUSH_POLL_MS, FlushOutcome, FlushRequest, FlushWatcher, LeaseForWrite, LeaseKeeper, acquireEditorLease, acquireLeaseForWrite, flushRequestPathFor, keepEditorLeaseAlive, pendingFlushRequests, watchFlushRequests };
+export { DEFAULT_FLUSH_WAIT_MS, EDITOR_LEASE_MS, EDITOR_RENEW_MS, FLUSH_POLL_MS, FlushOutcome, FlushRequest, FlushWatcher, LeaseForWrite, LeaseKeeper, PublicFlushRequest, acquireEditorLease, acquireLeaseForWrite, flushRequestPathFor, keepEditorLeaseAlive, pendingFlushRequests, watchFlushRequests };

package/dist/editor-lease.js

@@ -1,6 +1,6 @@
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
 import { fileVersionOf } from "./file-system.js";
-import { DEFAULT_LEASE_OWNER, acquireLease, readLease } from "./lock.js";
+import { DEFAULT_LEASE_OWNER, acquireLease, publicLockHolder, readLease } from "./lock.js";
 import { readSidecarFile, writeNewSidecarFile } from "./sidecar.js";
 import { Result } from "better-result";
 import { watch } from "node:fs";
@@ -62,6 +62,15 @@ const EDITOR_RENEW_MS = 10 * 1e3;
 const DEFAULT_FLUSH_WAIT_MS = 5 * 1e3;
 /** How often a writer retries the lease, and an editor re-checks for requests. */
 const FLUSH_POLL_MS = 100;
+const publicFlushRequest = ({ id, owner, pid, host, txId, requestedAt, deadline }) => ({
+	id,
+	owner,
+	pid,
+	host,
+	txId,
+	requestedAt,
+	deadline
+});
 const flushPrefixFor = (documentPath) => `.${path.basename(documentPath)}.folio-flush-`;
 const flushRequestPathFor = (documentPath, id) => path.join(path.dirname(documentPath), `${flushPrefixFor(documentPath)}${id}`);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -172,7 +181,7 @@ const acquireLeaseForWrite = async ({ documentPath, txId, force, owner = DEFAULT
 				lease: attempt.value,
 				flush: {
 					type: "flushed",
-					holder,
+					holder: publicLockHolder(holder),
 					versionBefore
 				}
 			});
@@ -191,7 +200,7 @@ const acquireLeaseForWrite = async ({ documentPath, txId, force, owner = DEFAULT
 			lease: last.value,
 			flush: {
 				type: "timedOut",
-				holder
+				holder: publicLockHolder(holder)
 			}
 		});
 		if (last.error.code !== FOLIO_CLI_ERROR_CODES.locked) return Result.err(last.error);
@@ -200,7 +209,7 @@ const acquireLeaseForWrite = async ({ documentPath, txId, force, owner = DEFAULT
 			message: `${documentPath} is held by ${holder.owner} (pid ${holder.pid} on ${holder.host}), which did not save and release it within ${String(flushWaitMs)} ms.`,
 			hint: "Save or close the document in the editor and retry, or pass --force to take the lease over.",
 			details: {
-				holder,
+				holder: publicLockHolder(holder),
 				flush: "timedOut",
 				flushWaitMs
 			}
@@ -220,7 +229,7 @@ const acquireEditorLease = async ({ documentPath, owner, txId = `editor-${random
 		code: FOLIO_CLI_ERROR_CODES.locked,
 		message: `A write to ${documentPath} is waiting to take the lease.`,
 		hint: "Retry after it commits, then reload the document.",
-		details: { pending }
+		details: { pending: pending.map(publicFlushRequest) }
 	}));
 	return await acquireLease({
 		documentPath,

package/dist/errors.d.ts

@@ -1,3 +1,5 @@
+import { PublicLockHolder } from "./lock.js";
+import { PublicFlushRequest } from "./editor-lease.js";
 //#region src/errors.d.ts
 /**
  * Process exit classes. The numbers match the stella command line's table so
@@ -43,6 +45,14 @@ declare const FOLIO_CLI_ERROR_CODES: {
 };
 type FolioCliErrorCode = (typeof FOLIO_CLI_ERROR_CODES)[keyof typeof FOLIO_CLI_ERROR_CODES];
 declare const exitCodeForError: (code: FolioCliErrorCode) => ExitCode;
+/** Public error context. Lease-bearing fields cannot accept internal records. */
+type PublicErrorDetails = {
+  readonly [key: string]: unknown;
+  readonly holder?: PublicLockHolder;
+  readonly pending?: readonly PublicFlushRequest[];
+  readonly token?: never;
+  readonly leaseToken?: never;
+};
 declare const FolioCliError_base: import("better-result").TaggedErrorClass<"FolioCliError">;
 /**
  * Every expected failure of a command or tool call. `hint` names the next
@@ -53,15 +63,15 @@ declare class FolioCliError extends FolioCliError_base<{
   code: FolioCliErrorCode;
   message: string;
   hint?: string;
-  details?: unknown;
+  details?: PublicErrorDetails;
 }> {}
 type CliErrorOptions = {
   code: FolioCliErrorCode;
   message: string;
   hint?: string | undefined;
-  details?: unknown;
+  details?: PublicErrorDetails;
 };
 /** 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 };
+export { EXIT_CODES, ExitCode, FOLIO_CLI_ERROR_CODES, FolioCliError, FolioCliErrorCode, PublicErrorDetails, cliError, exitCodeEntries, exitCodeForError };

package/dist/lock.d.ts

@@ -19,6 +19,11 @@ type LockHolder = {
   /** The holder saves and releases when a write asks it to (`editor-lease.ts`). */
   acceptsFlush?: true;
 };
+/** Holder metadata safe to return to a caller that does not own the lease. */
+type PublicLockHolder = Omit<LockHolder, "token"> & {
+  token?: never;
+};
+declare const publicLockHolder: ({ owner, pid, host, txId, acquiredAt, expiresAt, acceptsFlush }: LockHolder) => PublicLockHolder;
 declare const lockPathFor: (documentPath: string) => string;
 /** What is beside the document: no lock, or a lock with its parsed holder when it has one. */
 type LeaseState = {
@@ -75,4 +80,4 @@ declare const adoptLease: (documentPath: string, token: string) => Promise<Resul
  */
 declare const acquireLease: ({ documentPath, txId, force, owner, leaseMs, acceptsFlush, now }: AcquireLeaseOptions) => Promise<Result<AcquiredLease, FolioCliError>>;
 //#endregion
-export { AcquiredLease, DEFAULT_LEASE_OWNER, LeaseState, LockHolder, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, readLease };
+export { AcquiredLease, DEFAULT_LEASE_OWNER, LeaseState, LockHolder, PublicLockHolder, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, publicLockHolder, readLease };

package/dist/lock.js

@@ -32,6 +32,15 @@ const DEFAULT_LEASE_OWNER = "folio-cli";
 const OWNER_PATTERN = /^[\w.-]{1,64}$/u;
 /** A lease owner is 1 to 64 letters, digits, '.', '_' or '-'. */
 const isLeaseOwner = (value) => OWNER_PATTERN.test(value);
+const publicLockHolder = ({ owner, pid, host, txId, acquiredAt, expiresAt, acceptsFlush }) => ({
+	owner,
+	pid,
+	host,
+	txId,
+	acquiredAt,
+	expiresAt,
+	...acceptsFlush === true && { acceptsFlush }
+});
 const lockPathFor = (documentPath) => path.join(path.dirname(documentPath), `.${path.basename(documentPath)}.folio-lock`);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const parseHolder = (text) => {
@@ -95,7 +104,7 @@ const lockedError = (documentPath, state) => cliError({
 	code: FOLIO_CLI_ERROR_CODES.locked,
 	message: `${documentPath} is being written by another process${state.type === "held" ? ` (${state.holder.owner}, pid ${state.holder.pid} on ${state.holder.host})` : ""}.`,
 	hint: "Retry after it finishes, or pass --force to take the lease over.",
-	details: state.type === "held" ? { holder: state.holder } : void 0
+	...state.type === "held" && { details: { holder: publicLockHolder(state.holder) } }
 });
 const lostError = (documentPath) => cliError({
 	code: FOLIO_CLI_ERROR_CODES.locked,
@@ -214,7 +223,7 @@ const adoptLease = async (documentPath, token) => {
 		code: FOLIO_CLI_ERROR_CODES.locked,
 		message: `${documentPath} is not held under that lease token.`,
 		hint: "The lease expired or was taken over; acquire it again and retry.",
-		details: current.type === "held" ? { holder: current.holder } : void 0
+		...current.type === "held" && { details: { holder: publicLockHolder(current.holder) } }
 	}));
 	const { holder } = current;
 	const leaseMs = Math.max(Date.parse(holder.expiresAt) - Date.parse(holder.acquiredAt), 0);
@@ -260,4 +269,4 @@ const acquireLease = async ({ documentPath, txId, force, owner = DEFAULT_LEASE_O
 	return Result.err(lockedError(documentPath, { type: "free" }));
 };
 //#endregion
-export { DEFAULT_LEASE_OWNER, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, readLease };
+export { DEFAULT_LEASE_OWNER, TRANSACTION_LEASE_MS, acquireLease, adoptLease, isLeaseOwner, isStaleLease, lockPathFor, lockSwapPathFor, publicLockHolder, readLease };

package/dist/main-document-part.d.ts

@@ -0,0 +1,26 @@
+import { FolioCliError } from "./errors.js";
+import { Result } from "better-result";
+//#region src/main-document-part.d.ts
+/** Why a file is not a readable WordprocessingML package. */
+declare const INVALID_PACKAGE_REASONS: {
+  readonly notZip: "notZip";
+  readonly duplicatePartName: "duplicatePartName";
+  readonly contentTypesMissing: "contentTypesMissing";
+  readonly contentTypesInvalid: "contentTypesInvalid";
+  readonly relationshipsMissing: "relationshipsMissing";
+  readonly relationshipsInvalid: "relationshipsInvalid";
+  readonly mainRelationshipMissing: "mainRelationshipMissing";
+  readonly mainRelationshipAmbiguous: "mainRelationshipAmbiguous";
+  readonly mainPartMissing: "mainPartMissing";
+  readonly mainPartContentType: "mainPartContentType";
+  readonly mainPartRoot: "mainPartRoot";
+  readonly mainPartLocation: "mainPartLocation";
+};
+type InvalidPackageReason = (typeof INVALID_PACKAGE_REASONS)[keyof typeof INVALID_PACKAGE_REASONS];
+/**
+ * Refuse, as `invalid_document`, a file that is not a WordprocessingML
+ * package with a main document part folio reads.
+ */
+declare const checkWordprocessingPackage: (filePath: string, bytes: Uint8Array) => Promise<Result<void, FolioCliError>>;
+//#endregion
+export { INVALID_PACKAGE_REASONS, InvalidPackageReason, checkWordprocessingPackage };

package/dist/main-document-part.js

@@ -0,0 +1,323 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import path from "node:path";
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+import JSZip from "jszip";
+//#region src/main-document-part.ts
+/**
+* Whether a file is a WordprocessingML package at all, decided the way the
+* Open Packaging Conventions say to find its main part: the package
+* relationship of the office-document type names the part, the part exists,
+* `[Content_Types].xml` gives it a WordprocessingML main-document type, and
+* its root is a `document` in a WordprocessingML namespace.
+*
+* The folio parser reads whatever `.docx` it is handed and reports a missing
+* main part as a warning, so an archive holding no document opened as an
+* empty one. Checked where a file enters the CLI, a ZIP of unrelated entries
+* is refused before a read reports it as an empty document or a save commits
+* it over a real one.
+*
+* Every name is resolved by namespace URI, never by prefix, and both the
+* Transitional and the Strict relationship and WordprocessingML namespaces are
+* accepted.
+*/
+const CONTENT_TYPES_PART = "[Content_Types].xml";
+const PACKAGE_RELATIONSHIPS_PART = "_rels/.rels";
+/** The one main part the folio parser reads. */
+const READ_MAIN_DOCUMENT_PART = "word/document.xml";
+const CONTENT_TYPES_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types";
+const PACKAGE_RELATIONSHIPS_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/relationships";
+/** The office-document relationship type: Transitional, then Strict. */
+const OFFICE_DOCUMENT_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument", "http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument"]);
+const WORDPROCESSINGML_NAMESPACES = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/wordprocessingml/2006/main", "http://purl.oclc.org/ooxml/wordprocessingml/main"]);
+/** A document, a template, and their macro-enabled forms; Strict uses the same types. */
+const MAIN_DOCUMENT_CONTENT_TYPES = /* @__PURE__ */ new Set([
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml",
+	"application/vnd.ms-word.document.macroEnabled.main+xml",
+	"application/vnd.ms-word.template.macroEnabledTemplate.main+xml"
+]);
+/** `[Content_Types].xml` and `_rels/.rels` are indexes; this bounds their inflation. */
+const MAX_PACKAGE_INDEX_BYTES = 1024 * 1024;
+/** How much of the main part is inflated to find its root element. */
+const MAX_ROOT_SCAN_BYTES = 64 * 1024;
+/** Why a file is not a readable WordprocessingML package. */
+const INVALID_PACKAGE_REASONS = {
+	notZip: "notZip",
+	duplicatePartName: "duplicatePartName",
+	contentTypesMissing: "contentTypesMissing",
+	contentTypesInvalid: "contentTypesInvalid",
+	relationshipsMissing: "relationshipsMissing",
+	relationshipsInvalid: "relationshipsInvalid",
+	mainRelationshipMissing: "mainRelationshipMissing",
+	mainRelationshipAmbiguous: "mainRelationshipAmbiguous",
+	mainPartMissing: "mainPartMissing",
+	mainPartContentType: "mainPartContentType",
+	mainPartRoot: "mainPartRoot",
+	mainPartLocation: "mainPartLocation"
+};
+const refuse = (reason, message) => Result.err({
+	reason,
+	message
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const orderedParser = new XMLParser({
+	preserveOrder: true,
+	ignoreAttributes: false,
+	attributeNamePrefix: "",
+	parseAttributeValue: false,
+	parseTagValue: false,
+	processEntities: false,
+	ignoreDeclaration: true,
+	ignorePiTags: true
+});
+const splitName = (qualified) => {
+	const colon = qualified.indexOf(":");
+	return colon === -1 ? {
+		prefix: "",
+		localName: qualified
+	} : {
+		prefix: qualified.slice(0, colon),
+		localName: qualified.slice(colon + 1)
+	};
+};
+const stringAttributes = (value) => {
+	const attributes = {};
+	if (!isRecord(value)) return attributes;
+	for (const [name, attribute] of Object.entries(value)) if (typeof attribute === "string") attributes[name] = attribute;
+	return attributes;
+};
+/** The element children of one ordered node list, with namespaces in scope resolved. */
+const elementsOf = (nodes, scope) => {
+	if (!Array.isArray(nodes)) return [];
+	const elements = [];
+	for (const node of nodes) {
+		if (!isRecord(node)) continue;
+		const name = Object.keys(node).find((key) => key !== ":@" && key !== "#text");
+		if (name === void 0) continue;
+		const attributes = stringAttributes(node[":@"]);
+		const inner = new Map(scope);
+		for (const [attribute, value] of Object.entries(attributes)) if (attribute === "xmlns") inner.set("", value);
+		else if (attribute.startsWith("xmlns:")) inner.set(attribute.slice(6), value);
+		const { prefix, localName } = splitName(name);
+		elements.push({
+			namespace: inner.get(prefix),
+			localName,
+			attributes,
+			children: elementsOf(node[name], inner)
+		});
+	}
+	return elements;
+};
+/** The root element of a well-formed XML part, or `null`. */
+const parseRoot = (xml) => {
+	if (/<!DOCTYPE/iu.test(xml) || XMLValidator.validate(xml) !== true) return null;
+	const parsed = orderedParser.parse(xml);
+	const [root] = elementsOf(parsed, /* @__PURE__ */ new Map());
+	return root ?? null;
+};
+const childrenNamed = (element, namespace, localName) => element.children.filter((child) => child.namespace === namespace && child.localName === localName);
+/** Part names compare case-insensitively (ECMA-376 Part 2, 9.1.1.1). */
+const partKey = (name) => name.toLowerCase();
+/** Inflate at most `limit` bytes of an entry; `truncated` when it holds more. */
+const inflatePrefix = (entry, limit) => new Promise((resolve, reject) => {
+	const decoder = new TextDecoder();
+	let text = "";
+	let size = 0;
+	const stream = entry.internalStream("uint8array");
+	stream.on("data", (chunk) => {
+		const room = limit - size;
+		size += chunk.length;
+		text += decoder.decode(chunk.subarray(0, Math.max(0, room)), { stream: true });
+		if (size > limit) {
+			stream.pause();
+			resolve({
+				text: text + decoder.decode(),
+				truncated: true
+			});
+		}
+	}).on("error", reject).on("end", () => resolve({
+		text: text + decoder.decode(),
+		truncated: false
+	})).resume();
+});
+const readIndexPart = async ({ parts, name, missing, invalid }) => {
+	const entry = parts.get(partKey(name));
+	if (entry === void 0) return refuse(missing, `it has no ${name}.`);
+	const inflated = await Result.tryPromise({
+		try: () => inflatePrefix(entry, MAX_PACKAGE_INDEX_BYTES),
+		catch: () => ({
+			reason: invalid,
+			message: `its ${name} cannot be inflated.`
+		})
+	});
+	if (inflated.isErr()) return Result.err(inflated.error);
+	if (inflated.value.truncated) return refuse(invalid, `its ${name} is over ${String(MAX_PACKAGE_INDEX_BYTES)} bytes.`);
+	const root = parseRoot(inflated.value.text);
+	return root === null ? refuse(invalid, `its ${name} is not well-formed XML.`) : Result.ok(root);
+};
+/** The part a package-relative relationship target names, without its leading `/`. */
+const resolvePackageTarget = (target) => {
+	const decoded = Result.try({
+		try: () => decodeURIComponent(target),
+		catch: () => null
+	});
+	if (decoded.isErr()) return null;
+	const resolved = path.posix.normalize(path.posix.join("/", decoded.value));
+	return resolved === "/" ? null : resolved.slice(1);
+};
+const mainPartName = (relationships) => {
+	if (relationships.namespace !== PACKAGE_RELATIONSHIPS_NAMESPACE || relationships.localName !== "Relationships") return refuse(INVALID_PACKAGE_REASONS.relationshipsInvalid, `its ${PACKAGE_RELATIONSHIPS_PART} is not a relationships part.`);
+	const main = childrenNamed(relationships, PACKAGE_RELATIONSHIPS_NAMESPACE, "Relationship").filter(({ attributes }) => OFFICE_DOCUMENT_RELATIONSHIP_TYPES.has(attributes["Type"] ?? "") && attributes["TargetMode"] !== "External");
+	const [only, ...others] = main;
+	if (only === void 0) return refuse(INVALID_PACKAGE_REASONS.mainRelationshipMissing, "no package relationship names a main document part.");
+	if (others.length > 0) return refuse(INVALID_PACKAGE_REASONS.mainRelationshipAmbiguous, `${String(main.length)} package relationships name a main document part.`);
+	const part = resolvePackageTarget(only.attributes["Target"] ?? "");
+	return part === null ? refuse(INVALID_PACKAGE_REASONS.relationshipsInvalid, "the main document relationship has no usable target.") : Result.ok(part);
+};
+/** An `Override` for the part wins over the `Default` for its extension. */
+const contentTypeOf = ({ contentTypes, part }) => {
+	const partName = partKey(`/${part}`);
+	const override = childrenNamed(contentTypes, CONTENT_TYPES_NAMESPACE, "Override").find(({ attributes }) => partKey(attributes["PartName"] ?? "") === partName);
+	if (override !== void 0) return override.attributes["ContentType"];
+	const extension = partKey(path.posix.extname(part).slice(1));
+	return childrenNamed(contentTypes, CONTENT_TYPES_NAMESPACE, "Default").find(({ attributes }) => partKey(attributes["Extension"] ?? "") === extension)?.attributes["ContentType"];
+};
+/** The first element's name and namespace declarations, read from its start tag. */
+const rootOfPrefix = (xml) => {
+	const body = xml.replace(/^?(?:\s|<\?[\s\S]*?\?>|<!--[\s\S]*?-->)*/u, "");
+	const match = /^<([A-Za-z_][\w.:-]*)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*\/?>/u.exec(body);
+	if (match === null) return null;
+	const [, name = "", attributeText = ""] = match;
+	const scope = /* @__PURE__ */ new Map();
+	for (const [, attribute = "", double, single] of attributeText.matchAll(/([^\s=]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/gu)) {
+		const value = double ?? single ?? "";
+		if (attribute === "xmlns") scope.set("", value);
+		else if (attribute.startsWith("xmlns:")) scope.set(attribute.slice(6), value);
+	}
+	const { prefix, localName } = splitName(name);
+	return {
+		namespace: scope.get(prefix),
+		localName,
+		attributes: {},
+		children: []
+	};
+};
+const ZIP_END_SIGNATURE = 101010256;
+const ZIP64_END_SIGNATURE = 101075792;
+const ZIP64_LOCATOR_SIGNATURE = 117853008;
+const ZIP_CENTRAL_MEMBER_SIGNATURE = 33639248;
+const ZIP_END_LENGTH = 22;
+const ZIP_CENTRAL_MEMBER_LENGTH = 46;
+const ZIP_MAX_COMMENT_LENGTH = 65535;
+/** Read central-directory names before JSZip stores members by name. */
+const checkRawMemberNames = (bytes) => {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let end = -1;
+	for (let offset = bytes.length - ZIP_END_LENGTH; offset >= Math.max(0, bytes.length - ZIP_END_LENGTH - ZIP_MAX_COMMENT_LENGTH); offset -= 1) if (view.getUint32(offset, true) === ZIP_END_SIGNATURE && offset + ZIP_END_LENGTH + view.getUint16(offset + 20, true) === bytes.length) {
+		end = offset;
+		break;
+	}
+	if (end < 0) return refuse(INVALID_PACKAGE_REASONS.notZip, "it has no readable ZIP directory.");
+	let count = view.getUint16(end + 10, true);
+	let size = view.getUint32(end + 12, true);
+	let directoryEnd = end;
+	if (count === 65535 || size === 4294967295 || view.getUint32(end + 16, true) === 4294967295) {
+		const locator = end - 20;
+		if (locator < 0 || view.getUint32(locator, true) !== ZIP64_LOCATOR_SIGNATURE) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP64 directory is missing.");
+		const zip64Offset = Number(view.getBigUint64(locator + 8, true));
+		if (!Number.isSafeInteger(zip64Offset) || zip64Offset < 0 || zip64Offset + 56 > locator || view.getUint32(zip64Offset, true) !== ZIP64_END_SIGNATURE) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP64 directory is invalid.");
+		count = Number(view.getBigUint64(zip64Offset + 32, true));
+		size = Number(view.getBigUint64(zip64Offset + 40, true));
+		directoryEnd = zip64Offset;
+	}
+	if (!Number.isSafeInteger(count) || !Number.isSafeInteger(size) || size > directoryEnd) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP directory is invalid.");
+	const seen = /* @__PURE__ */ new Set();
+	let offset = directoryEnd - size;
+	for (let index = 0; index < count; index += 1) {
+		if (offset + ZIP_CENTRAL_MEMBER_LENGTH > directoryEnd || view.getUint32(offset, true) !== ZIP_CENTRAL_MEMBER_SIGNATURE) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP directory is invalid.");
+		const nameLength = view.getUint16(offset + 28, true);
+		const extraLength = view.getUint16(offset + 30, true);
+		const commentLength = view.getUint16(offset + 32, true);
+		const next = offset + ZIP_CENTRAL_MEMBER_LENGTH + nameLength + extraLength + commentLength;
+		if (next > directoryEnd) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP directory is invalid.");
+		const name = Buffer.from(bytes.subarray(offset + ZIP_CENTRAL_MEMBER_LENGTH, offset + ZIP_CENTRAL_MEMBER_LENGTH + nameLength)).toString("hex");
+		if (seen.has(name)) return refuse(INVALID_PACKAGE_REASONS.duplicatePartName, "two ZIP entries have the same name.");
+		seen.add(name);
+		offset = next;
+	}
+	if (offset !== directoryEnd) return refuse(INVALID_PACKAGE_REASONS.notZip, "its ZIP directory is invalid.");
+	return Result.ok();
+};
+const checkPackage = async (bytes) => {
+	const rawNames = checkRawMemberNames(bytes);
+	if (rawNames.isErr()) return rawNames;
+	const zip = await Result.tryPromise({
+		try: () => JSZip.loadAsync(bytes),
+		catch: () => ({
+			reason: INVALID_PACKAGE_REASONS.notZip,
+			message: "it is not a readable ZIP archive."
+		})
+	});
+	if (zip.isErr()) return Result.err(zip.error);
+	const parts = /* @__PURE__ */ new Map();
+	for (const [name, entry] of Object.entries(zip.value.files)) {
+		if (entry.dir) continue;
+		const key = partKey(name.replace(/^\//u, ""));
+		if (parts.has(key)) return refuse(INVALID_PACKAGE_REASONS.duplicatePartName, `two entries share the part name ${name}.`);
+		parts.set(key, entry);
+	}
+	const contentTypes = await readIndexPart({
+		parts,
+		name: CONTENT_TYPES_PART,
+		missing: INVALID_PACKAGE_REASONS.contentTypesMissing,
+		invalid: INVALID_PACKAGE_REASONS.contentTypesInvalid
+	});
+	if (contentTypes.isErr()) return Result.err(contentTypes.error);
+	if (contentTypes.value.namespace !== CONTENT_TYPES_NAMESPACE || contentTypes.value.localName !== "Types") return refuse(INVALID_PACKAGE_REASONS.contentTypesInvalid, `its ${CONTENT_TYPES_PART} is not a content types part.`);
+	const relationships = await readIndexPart({
+		parts,
+		name: PACKAGE_RELATIONSHIPS_PART,
+		missing: INVALID_PACKAGE_REASONS.relationshipsMissing,
+		invalid: INVALID_PACKAGE_REASONS.relationshipsInvalid
+	});
+	if (relationships.isErr()) return Result.err(relationships.error);
+	const part = mainPartName(relationships.value);
+	if (part.isErr()) return Result.err(part.error);
+	const entry = parts.get(partKey(part.value));
+	if (entry === void 0) return refuse(INVALID_PACKAGE_REASONS.mainPartMissing, `its main document part /${part.value} is missing.`);
+	const contentType = contentTypeOf({
+		contentTypes: contentTypes.value,
+		part: part.value
+	});
+	if (contentType === void 0 || !MAIN_DOCUMENT_CONTENT_TYPES.has(contentType)) return refuse(INVALID_PACKAGE_REASONS.mainPartContentType, `its main part /${part.value} has content type ${contentType ?? "(none)"}, not a WordprocessingML document.`);
+	const prefix = await Result.tryPromise({
+		try: () => inflatePrefix(entry, MAX_ROOT_SCAN_BYTES),
+		catch: () => ({
+			reason: INVALID_PACKAGE_REASONS.mainPartRoot,
+			message: `its main part /${part.value} cannot be inflated.`
+		})
+	});
+	if (prefix.isErr()) return Result.err(prefix.error);
+	const root = rootOfPrefix(prefix.value.text);
+	if (root === null || root.localName !== "document" || !WORDPROCESSINGML_NAMESPACES.has(root.namespace ?? "")) return refuse(INVALID_PACKAGE_REASONS.mainPartRoot, `its main part /${part.value} is not a WordprocessingML document.`);
+	if (partKey(part.value) !== partKey(READ_MAIN_DOCUMENT_PART)) return refuse(INVALID_PACKAGE_REASONS.mainPartLocation, `its main document is /${part.value}; folio reads it only at /${READ_MAIN_DOCUMENT_PART}.`);
+	return Result.ok();
+};
+/**
+* Refuse, as `invalid_document`, a file that is not a WordprocessingML
+* package with a main document part folio reads.
+*/
+const checkWordprocessingPackage = async (filePath, bytes) => {
+	const checked = await checkPackage(bytes);
+	if (checked.isOk()) return Result.ok();
+	const { reason, message } = checked.error;
+	return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+		message: `${filePath} is not a .docx package: ${message}`,
+		hint: "Pass a .docx saved by a word processor or by folio.",
+		details: { reason }
+	}));
+};
+//#endregion
+export { INVALID_PACKAGE_REASONS, checkWordprocessingPackage };

package/dist/output.d.ts

@@ -1,4 +1,4 @@
-import { FolioCliError, FolioCliErrorCode } from "./errors.js";
+import { FolioCliError, FolioCliErrorCode, PublicErrorDetails } from "./errors.js";
 //#region src/output.d.ts
 declare const OUTPUT_FORMATS: readonly ["json", "text"];
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
@@ -7,7 +7,7 @@ type FailureBody = {
   code: FolioCliErrorCode;
   message: string;
   hint?: string;
-  details?: unknown;
+  details?: PublicErrorDetails;
 };
 type Envelope = {
   ok: true;

package/dist/package-parts.d.ts

@@ -17,7 +17,8 @@ declare const nextRevisionIdSeed: (bytes: Uint8Array) => Promise<Result<number,
  * Check what a save wrote before it replaces anything: the package opens,
  * every changed XML part is well formed, every relationship id a changed
  * part references resolves, every internal target a changed `.rels` part
- * names exists, and the package parses as a document again.
+ * names exists, the package still has the main document part folio reads,
+ * and it parses as a document again.
  */
 declare const checkPackageIntegrity: (bytes: Uint8Array<ArrayBuffer>, changedParts: readonly ChangedPart[]) => Promise<Result<void, FolioCliError>>;
 //#endregion

package/dist/package-parts.js

@@ -1,4 +1,5 @@
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { checkWordprocessingPackage } from "./main-document-part.js";
 import { Result } from "better-result";
 import path from "node:path";
 import { FolioDocxReviewer } from "@stll/folio-core/server";
@@ -147,7 +148,8 @@ const checkChangedPart = async ({ zip, parts, part }) => {
 * Check what a save wrote before it replaces anything: the package opens,
 * every changed XML part is well formed, every relationship id a changed
 * part references resolves, every internal target a changed `.rels` part
-* names exists, and the package parses as a document again.
+* names exists, the package still has the main document part folio reads,
+* and it parses as a document again.
 */
 const checkPackageIntegrity = async (bytes, changedParts) => {
 	const zip = await loadZip(bytes);
@@ -162,6 +164,8 @@ const checkPackageIntegrity = async (bytes, changedParts) => {
 		});
 		if (problem !== null) return Result.err(integrityError(`The saved package failed validation: ${problem}`));
 	}
+	const mainPart = await checkWordprocessingPackage("The saved package", bytes);
+	if (mainPart.isErr()) return Result.err(integrityError(mainPart.error.message));
 	const reopened = await Result.tryPromise({
 		try: () => FolioDocxReviewer.fromBuffer(bytes.slice().buffer),
 		catch: (error) => integrityError(`The saved package does not reopen: ${error instanceof Error ? error.message : String(error)}`)

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.3.0";
+var version = "0.3.2";
 //#endregion
 export { version };

package/dist/preview-commands.js

@@ -210,10 +210,7 @@ const runServe = async (rest, io) => {
 		documentPath: input,
 		port
 	});
-	if (started.isErr()) return emit(io, format.value, Result.err(cliError({
-		code: FOLIO_CLI_ERROR_CODES.invalidInput,
-		message: started.error.message
-	})));
+	if (started.isErr()) return emit(io, format.value, started);
 	const exit = emit(io, format.value, Result.ok({
 		url: started.value.url,
 		path: path.resolve(input)

package/dist/serve.d.ts

@@ -1,3 +1,4 @@
+import { FolioCliError } from "./errors.js";
 import { Result } from "better-result";
 //#region src/serve.d.ts
 declare const PREVIEW_HOST = "127.0.0.1";
@@ -12,6 +13,6 @@ type PreviewServer = {
   close: () => Promise<void>;
 };
 /** Serve the preview until {@link PreviewServer.close}. */
-declare const startPreviewServer: ({ documentPath, port }: PreviewServerOptions) => Promise<Result<PreviewServer, Error>>;
+declare const startPreviewServer: ({ documentPath, port }: PreviewServerOptions) => Promise<Result<PreviewServer, FolioCliError>>;
 //#endregion
 export { PREVIEW_HOST, PreviewServer, PreviewServerOptions, startPreviewServer };

package/dist/serve.js

@@ -1,4 +1,5 @@
 import { readDocumentFile } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
 import { latestCommitFor } from "./journal.js";
 import { buildDisplayList, displayListHtml } from "./render.js";
 import { SIDECAR_DIRECTORY } from "./sidecar.js";
@@ -81,7 +82,7 @@ const DOCUMENT_CSP = "default-src 'none'; img-src data:; font-src data:; style-s
 /** Serve the preview until {@link PreviewServer.close}. */
 const startPreviewServer = async ({ documentPath, port }) => {
 	const initial = await readDocumentFile(documentPath);
-	if (initial.isErr()) return Result.err(new Error(initial.error.message));
+	if (initial.isErr()) return Result.err(initial.error);
 	const realPath = initial.value.path;
 	const title = path.basename(realPath);
 	const prefix = `/${randomBytes(24).toString("base64url")}/`;
@@ -215,7 +216,10 @@ const startPreviewServer = async ({ documentPath, port }) => {
 	if ((await Result.tryPromise(() => new Promise((resolve, reject) => {
 		server.once("error", reject);
 		server.listen(port, "127.0.0.1", () => resolve());
-	}))).isErr()) return Result.err(/* @__PURE__ */ new Error(`Cannot listen on ${PREVIEW_HOST}:${String(port)}.`));
+	}))).isErr()) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.invalidInput,
+		message: `Cannot listen on ${PREVIEW_HOST}:${String(port)}.`
+	}));
 	const address = server.address();
 	boundPort = typeof address === "object" && address !== null ? address.port : port;
 	const watchers = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Command line and stdio MCP server for reading, reviewing, and redlining .docx files with folio: tracked-change edits, comments, and comparisons written atomically with version preconditions.",
   "keywords": [
     "cli",
@@ -70,8 +70,8 @@
     "@fontsource/source-sans-3": "^5.2.9",
     "@fontsource/tinos": "^5.2.7",
     "@modelcontextprotocol/server": "2.0.0",
-    "@stll/folio-agents": "^0.14.1",
-    "@stll/folio-core": "^0.51.0",
+    "@stll/folio-agents": "^0.15.0",
+    "@stll/folio-core": "^0.53.0",
     "better-result": "3.0.1",
     "fast-xml-parser": "^5.10.1",
     "jszip": "3.10.1"