pi-filler 0.0.0

package/COPYING.md

@@ -0,0 +1,9 @@
+# Licensing and attribution
+
+The project source and template files are released under the MIT License
+in `LICENSE` unless a file states otherwise.
+
+The documentation build follows the design of João Oliveira Santos and
+Carlos Pinto Machado's `make it_stop` project. This repository does not
+vendor the upstream project; it keeps a small project-local Make-based
+implementation so the package remains self-contained.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Oliveira Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# pi-filler
+
+<p align="center"><img src="logo.png" alt="pi-filler logo" width="220"></p>
+
+Deterministic DOCX and PDF tooling for Pi.
+
+`pi-filler` fills document-handling gaps between ordinary Markdown
+workflows and final office-format requirements. It delegates common
+conversion and PDF extraction to mature command-line tools while keeping
+Word-specific mutations narrow and inspectable.
+
+## Status
+
+Early experimental release. The tool schema and supported document
+operations may change before 1.0.0.
+
+## Tool
+
+The extension exposes one `filler` tool:
+
+```text
+format: docx | pdf
+action: read | search | write | patch
+view: text | formatting | image
+```
+
+Unsupported combinations and operation-irrelevant parameters fail
+explicitly. DOCX patching also accepts `dry_run: true` to validate and
+report the requested result without writing the output file.
+
+## PDF
+
+- Read text with layout preservation and optional page ranges.
+- Search with literal or regular-expression queries and page numbers.
+- Restrict searches to optional page ranges.
+- Render selected pages to PNG files without destroying prior output
+  when rendering fails.
+- PDF writing and patching are not supported.
+
+## DOCX
+
+- Read and search text through Pandoc.
+- Render selected pages to PNG through LibreOffice and the existing PDF
+  rendering path.
+- Generate DOCX from Markdown with an optional reference document.
+- Validate generated DOCX before replacing the requested output.
+- Inspect page setup, margins, sections, line numbering, page
+  numbering, comments, inserted/deleted tracked-change markers, and
+  common core metadata.
+- Patch page setup, margins, line numbering, page numbering, and common
+  core metadata.
+- Use `clearCoreMetadata` to clear common `docProps/core.xml` fields.
+  This does **not** remove comment authors, revision authors, or every
+  possible identity-bearing property in a DOCX.
+
+Page setup, margins, line numbering, and page numbering patches affect
+the first section only. Core-metadata patches are document-level.
+Untouched ZIP package parts remain content-identical. XML parts that are
+edited are parsed and serialized again, so lexical formatting, prefix
+choices, or element ordering inside those edited parts may change.
+
+## External tools
+
+Required for the corresponding operations:
+
+- `pandoc` for DOCX text conversion and generation.
+- `libreoffice` for DOCX image rendering.
+- `pdftotext` for PDF text extraction.
+- `pdftocairo` for PDF and DOCX page rendering.
+- `pdfgrep` for page-aware PDF search.
+
+## Development
+
+```sh
+npm install
+make verify
+make site
+```
+
+Dependencies and CI actions follow current upstream releases rather than
+being pinned. GitLab is canonical and the only release authority.
+GitHub may mirror the repository, verify it, and publish GitHub Pages.

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "pi-filler",
+	"version": "0.0.0",
+	"description": "Deterministic DOCX and PDF tooling for Pi",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"docx",
+		"pdf",
+		"pandoc",
+		"document-processing"
+	],
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://gitlab.com/Joao-O-Santos/pi-filler.git"
+	},
+	"bugs": {
+		"url": "https://gitlab.com/Joao-O-Santos/pi-filler/-/issues"
+	},
+	"homepage": "https://gitlab.com/Joao-O-Santos/pi-filler",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"logo.png",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "node --import tsx --test test/*.test.ts",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint src test scripts",
+		"format:check": "biome ci --linter-enabled=false --assist-enabled=false src test scripts biome.json package.json tsconfig.json",
+		"format:fix": "biome check --write src test scripts biome.json package.json tsconfig.json",
+		"markdown:check": "node scripts/format-markdown.mjs",
+		"markdown:fix": "node scripts/format-markdown.mjs --write",
+		"style": "npm run lint && npm run format:check && npm run markdown:check",
+		"check": "npm run typecheck && npm run style && npm test",
+		"site": "make site"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "latest",
+		"@earendil-works/pi-ai": "latest",
+		"@earendil-works/pi-coding-agent": "latest",
+		"@earendil-works/pi-tui": "latest",
+		"@types/node": "latest",
+		"tsx": "latest",
+		"typebox": "latest",
+		"typescript": "latest"
+	},
+	"dependencies": {
+		"fast-xml-parser": "latest",
+		"fflate": "latest"
+	}
+}

package/src/docx.ts

@@ -0,0 +1,518 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve } from "node:path";
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import { unzipSync, zipSync } from "fflate";
+
+export interface DocxPatchSet {
+	page?: { width?: number; height?: number; orientation?: "portrait" | "landscape" };
+	margins?: {
+		top?: number;
+		bottom?: number;
+		left?: number;
+		right?: number;
+		header?: number;
+		footer?: number;
+		gutter?: number;
+	};
+	lineNumbering?: {
+		mode?: "off" | "continuous" | "newPage" | "newSection";
+		start?: number;
+		count_by?: number;
+	};
+	pageNumbering?: { start?: number; format?: string };
+	metadata?: {
+		title?: string;
+		subject?: string;
+		creator?: string;
+		keywords?: string;
+		description?: string;
+		lastModifiedBy?: string;
+	};
+	clearCoreMetadata?: boolean;
+}
+
+export interface DocxFormatting {
+	page: { width?: number; height?: number; orientation?: string };
+	margins: Record<string, number>;
+	sectionCount: number;
+	lineNumbering: { mode: string; start?: number; count_by?: number };
+	pageNumbering: { start?: number; format?: string };
+	comments: number;
+	trackedChanges: number;
+	metadata: Record<string, string>;
+}
+
+export interface DocxPatchResult {
+	formatting: DocxFormatting;
+	changedParts: string[];
+	preservedParts: string[];
+	written: boolean;
+}
+
+type Package = Record<string, Uint8Array>;
+type XmlObject = Record<string, unknown>;
+
+const WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const CORE_NS = "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
+const DC_NS = "http://purl.org/dc/elements/1.1/";
+
+const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+const builder = new XMLBuilder({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	format: false,
+});
+
+function isObject(value: unknown): value is XmlObject {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function localName(name: string): string {
+	return name.replace(/^@_/, "").split(":").at(-1) ?? name;
+}
+
+function parseXml(bytes: Uint8Array | undefined, part: string): XmlObject {
+	if (!bytes) throw new Error(`DOCX is missing required part ${part}`);
+	try {
+		return parser.parse(new TextDecoder().decode(bytes), true) as XmlObject;
+	} catch (error) {
+		throw new Error(`Invalid XML in ${part}: ${error instanceof Error ? error.message : error}`);
+	}
+}
+
+function serializeXml(value: XmlObject): Uint8Array {
+	return new TextEncoder().encode(builder.build(value));
+}
+
+function unpack(bytes: Uint8Array): Package {
+	try {
+		return unzipSync(bytes);
+	} catch (error) {
+		throw new Error(`Invalid DOCX ZIP package: ${error instanceof Error ? error.message : error}`);
+	}
+}
+
+function findAll(value: unknown, suffix: string, found: XmlObject[] = []): XmlObject[] {
+	if (!value || typeof value !== "object") return found;
+	for (const [key, child] of Object.entries(value)) {
+		if (!key.startsWith("@_") && localName(key) === suffix) {
+			for (const item of Array.isArray(child) ? child : [child]) {
+				if (isObject(item)) found.push(item);
+			}
+		}
+		findAll(child, suffix, found);
+	}
+	return found;
+}
+
+function first(value: unknown, suffix: string): XmlObject | undefined {
+	return findAll(value, suffix)[0];
+}
+
+function directObject(value: XmlObject | undefined, suffix: string): XmlObject | undefined {
+	if (!value) return undefined;
+	for (const [key, child] of Object.entries(value)) {
+		if (key.startsWith("@_") || localName(key) !== suffix) continue;
+		const candidate = Array.isArray(child) ? child[0] : child;
+		return isObject(candidate) ? candidate : undefined;
+	}
+	return undefined;
+}
+
+function rootObject(value: XmlObject, suffix: string): XmlObject {
+	const root = directObject(value, suffix);
+	if (!root) throw new Error(`DOCX XML is missing ${suffix}`);
+	return root;
+}
+
+function attr(value: XmlObject | undefined, name: string): string | undefined {
+	if (!value) return undefined;
+	for (const [key, child] of Object.entries(value)) {
+		if (key.startsWith("@_") && localName(key) === name && child !== undefined) {
+			return String(child);
+		}
+	}
+	return undefined;
+}
+
+function numberAttr(value: XmlObject | undefined, name: string): number | undefined {
+	const raw = attr(value, name);
+	return raw === undefined ? undefined : Number(raw);
+}
+
+function namespacePrefix(root: XmlObject, uri: string, preferred: string): string {
+	for (const [key, value] of Object.entries(root)) {
+		if (key.startsWith("@_xmlns:") && value === uri) return key.slice("@_xmlns:".length);
+	}
+	root[`@_xmlns:${preferred}`] = uri;
+	return preferred;
+}
+
+function setAttr(value: XmlObject, name: string, setting: number | string, prefix: string): void {
+	const existing = Object.keys(value).find(
+		(key) => key.startsWith("@_") && localName(key) === name,
+	);
+	value[existing ?? `@_${prefix}:${name}`] = String(setting);
+}
+
+function removeDirect(value: XmlObject, name: string): void {
+	for (const key of Object.keys(value)) {
+		if (!key.startsWith("@_") && localName(key) === name) delete value[key];
+	}
+}
+
+function countTags(value: unknown, suffix: string): number {
+	return findAll(value, suffix).length;
+}
+
+function hasValues(value: object | undefined): boolean {
+	return Boolean(value && Object.keys(value).length > 0);
+}
+
+const metadataNamespaces: Record<string, string> = {
+	title: DC_NS,
+	subject: DC_NS,
+	creator: DC_NS,
+	keywords: CORE_NS,
+	description: DC_NS,
+	lastModifiedBy: CORE_NS,
+};
+
+function childText(value: XmlObject, name: string): string | undefined {
+	for (const [key, child] of Object.entries(value)) {
+		if (key.startsWith("@_") || localName(key) !== name) continue;
+		if (typeof child === "string" || typeof child === "number") return String(child);
+		if (isObject(child)) {
+			const text = child["#text"];
+			if (typeof text === "string" || typeof text === "number") return String(text);
+		}
+	}
+	return undefined;
+}
+
+function setChildText(value: XmlObject, name: string, text: string): void {
+	const existing = Object.keys(value).find(
+		(key) => !key.startsWith("@_") && localName(key) === name,
+	);
+	if (existing) {
+		const child = value[existing];
+		if (isObject(child)) child["#text"] = text;
+		else value[existing] = text;
+		return;
+	}
+	const uri = metadataNamespaces[name] ?? DC_NS;
+	const prefix = namespacePrefix(value, uri, uri === CORE_NS ? "cp" : "dc");
+	value[`${prefix}:${name}`] = text;
+}
+
+function coreMetadata(pkg: Package): Record<string, string> {
+	const bytes = pkg["docProps/core.xml"];
+	if (!bytes) return {};
+	const props = rootObject(parseXml(bytes, "docProps/core.xml"), "coreProperties");
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(metadataNamespaces)) {
+		const value = childText(props, name);
+		if (value !== undefined) result[name] = value;
+	}
+	return result;
+}
+
+function countTrackedChanges(pkg: Package, document: XmlObject): number {
+	let count = countTags(document, "ins") + countTags(document, "del");
+	const contentPart = /^word\/(?:header\d+|footer\d+|footnotes|endnotes|comments)\.xml$/;
+	for (const [part, bytes] of Object.entries(pkg)) {
+		if (!contentPart.test(part)) continue;
+		const content = parseXml(bytes, part);
+		count += countTags(content, "ins") + countTags(content, "del");
+	}
+	return count;
+}
+
+function inspectPackage(pkg: Package): DocxFormatting {
+	const document = parseXml(pkg["word/document.xml"], "word/document.xml");
+	const sectPrs = findAll(document, "sectPr");
+	const section = sectPrs[0];
+	const size = directObject(section, "pgSz");
+	const margin = directObject(section, "pgMar");
+	const line = directObject(section, "lnNumType");
+	const pageNum = directObject(section, "pgNumType");
+	return {
+		page: {
+			width: numberAttr(size, "w"),
+			height: numberAttr(size, "h"),
+			orientation: size ? (attr(size, "orient") ?? "portrait") : undefined,
+		},
+		margins: Object.fromEntries(
+			["top", "bottom", "left", "right", "header", "footer", "gutter"]
+				.map((name) => [name, numberAttr(margin, name)])
+				.filter((entry): entry is [string, number] => entry[1] !== undefined),
+		),
+		sectionCount: sectPrs.length,
+		lineNumbering: {
+			mode: line ? (attr(line, "restart") ?? "newPage") : "off",
+			start: numberAttr(line, "start"),
+			count_by: numberAttr(line, "countBy"),
+		},
+		pageNumbering: { start: numberAttr(pageNum, "start"), format: attr(pageNum, "fmt") },
+		comments: pkg["word/comments.xml"]
+			? countTags(parseXml(pkg["word/comments.xml"], "word/comments.xml"), "comment")
+			: 0,
+		trackedChanges: countTrackedChanges(pkg, document),
+		metadata: coreMetadata(pkg),
+	};
+}
+
+function firstSection(document: XmlObject, prefix: string): XmlObject {
+	const existing = first(document, "sectPr");
+	if (existing) return existing;
+	const body = first(document, "body");
+	if (!body) throw new Error("DOCX is missing document body");
+	const section: XmlObject = {};
+	body[`${prefix}:sectPr`] = section;
+	return section;
+}
+
+function ensureChild(parent: XmlObject, name: string, prefix: string): XmlObject {
+	let child = directObject(parent, name);
+	if (!child) {
+		child = {};
+		parent[`${prefix}:${name}`] = child;
+	}
+	return child;
+}
+
+function patchPage(
+	section: XmlObject,
+	patch: NonNullable<DocxPatchSet["page"]>,
+	prefix: string,
+): void {
+	const size = ensureChild(section, "pgSz", prefix);
+	const width = numberAttr(size, "w");
+	const height = numberAttr(size, "h");
+	if (
+		patch.orientation !== undefined &&
+		patch.width === undefined &&
+		patch.height === undefined &&
+		width !== undefined &&
+		height !== undefined &&
+		((patch.orientation === "landscape" && width < height) ||
+			(patch.orientation === "portrait" && width > height))
+	) {
+		setAttr(size, "w", height, prefix);
+		setAttr(size, "h", width, prefix);
+	}
+	if (patch.width !== undefined) setAttr(size, "w", patch.width, prefix);
+	if (patch.height !== undefined) setAttr(size, "h", patch.height, prefix);
+	if (patch.orientation !== undefined) setAttr(size, "orient", patch.orientation, prefix);
+}
+
+function applyPatch(pkg: Package, patch: DocxPatchSet): string[] {
+	const changed = new Set<string>();
+	const documentPatch =
+		hasValues(patch.page) ||
+		hasValues(patch.margins) ||
+		hasValues(patch.lineNumbering) ||
+		hasValues(patch.pageNumbering);
+	if (documentPatch) {
+		const document = parseXml(pkg["word/document.xml"], "word/document.xml");
+		const documentRoot = rootObject(document, "document");
+		const prefix = namespacePrefix(documentRoot, WORD_NS, "w");
+		const sectPr = firstSection(document, prefix);
+
+		if (hasValues(patch.page)) patchPage(sectPr, patch.page ?? {}, prefix);
+		if (hasValues(patch.margins)) {
+			const margin = ensureChild(sectPr, "pgMar", prefix);
+			for (const [name, value] of Object.entries(patch.margins ?? {})) {
+				setAttr(margin, name, value, prefix);
+			}
+		}
+		if (hasValues(patch.lineNumbering)) {
+			if (patch.lineNumbering?.mode === "off") removeDirect(sectPr, "lnNumType");
+			else {
+				const line = ensureChild(sectPr, "lnNumType", prefix);
+				if (patch.lineNumbering?.mode) {
+					setAttr(line, "restart", patch.lineNumbering.mode, prefix);
+				}
+				if (patch.lineNumbering?.start !== undefined) {
+					setAttr(line, "start", patch.lineNumbering.start, prefix);
+				}
+				if (patch.lineNumbering?.count_by !== undefined) {
+					setAttr(line, "countBy", patch.lineNumbering.count_by, prefix);
+				}
+			}
+		}
+		if (hasValues(patch.pageNumbering)) {
+			const page = ensureChild(sectPr, "pgNumType", prefix);
+			if (patch.pageNumbering?.start !== undefined) {
+				setAttr(page, "start", patch.pageNumbering.start, prefix);
+			}
+			if (patch.pageNumbering?.format !== undefined) {
+				setAttr(page, "fmt", patch.pageNumbering.format, prefix);
+			}
+		}
+		pkg["word/document.xml"] = serializeXml(document);
+		changed.add("word/document.xml");
+	}
+
+	if (hasValues(patch.metadata) || patch.clearCoreMetadata) {
+		const core = parseXml(pkg["docProps/core.xml"], "docProps/core.xml");
+		const props = rootObject(core, "coreProperties");
+		if (patch.clearCoreMetadata) {
+			for (const name of Object.keys(metadataNamespaces)) {
+				if (childText(props, name) !== undefined) setChildText(props, name, "");
+			}
+		}
+		for (const [name, value] of Object.entries(patch.metadata ?? {})) {
+			setChildText(props, name, value);
+		}
+		pkg["docProps/core.xml"] = serializeXml(core);
+		changed.add("docProps/core.xml");
+	}
+	return [...changed];
+}
+
+function validatePatch(patch: DocxPatchSet): void {
+	const requested =
+		hasValues(patch.page) ||
+		hasValues(patch.margins) ||
+		hasValues(patch.lineNumbering) ||
+		hasValues(patch.pageNumbering) ||
+		hasValues(patch.metadata) ||
+		patch.clearCoreMetadata === true;
+	if (!requested) throw new Error("DOCX patch requires at least one change");
+	if (
+		patch.lineNumbering?.mode === "off" &&
+		(patch.lineNumbering.start !== undefined || patch.lineNumbering.count_by !== undefined)
+	) {
+		throw new Error("Line numbering mode=off cannot include start or count_by");
+	}
+}
+
+function validateRequested(formatting: DocxFormatting, patch: DocxPatchSet): void {
+	if (patch.page) {
+		for (const [key, value] of Object.entries(patch.page)) {
+			if (formatting.page[key as keyof typeof formatting.page] !== value) {
+				throw new Error(`DOCX page patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.margins) {
+		for (const [key, value] of Object.entries(patch.margins)) {
+			if (formatting.margins[key] !== value) {
+				throw new Error(`DOCX margin patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.lineNumbering) {
+		for (const [key, value] of Object.entries(patch.lineNumbering)) {
+			if (formatting.lineNumbering[key as keyof typeof formatting.lineNumbering] !== value) {
+				throw new Error(`DOCX line numbering patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.pageNumbering) {
+		for (const [key, value] of Object.entries(patch.pageNumbering)) {
+			if (formatting.pageNumbering[key as keyof typeof formatting.pageNumbering] !== value) {
+				throw new Error(`DOCX page numbering patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.metadata) {
+		for (const [key, value] of Object.entries(patch.metadata)) {
+			if (formatting.metadata[key] !== value) {
+				throw new Error(`DOCX metadata patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.clearCoreMetadata) {
+		for (const name of Object.keys(metadataNamespaces)) {
+			if (patch.metadata?.[name as keyof NonNullable<DocxPatchSet["metadata"]>] !== undefined) {
+				continue;
+			}
+			if (formatting.metadata[name]) {
+				throw new Error(`DOCX core metadata clearing validation failed for ${name}`);
+			}
+		}
+	}
+}
+
+function relationshipBase(part: string): string {
+	if (part.startsWith("_rels/")) return "";
+	const marker = "/_rels/";
+	const index = part.indexOf(marker);
+	return index === -1 ? posix.dirname(part) : part.slice(0, index);
+}
+
+function validateRelationships(pkg: Package): void {
+	for (const part of Object.keys(pkg).filter((name) => name.endsWith(".rels"))) {
+		const root = parseXml(pkg[part], part);
+		for (const relationship of findAll(root, "Relationship")) {
+			const target = attr(relationship, "Target");
+			if (!target || attr(relationship, "TargetMode") === "External") continue;
+			const normalized = target.startsWith("/")
+				? posix.normalize(target.slice(1))
+				: posix.normalize(posix.join(relationshipBase(part), target));
+			if (!pkg[normalized]) {
+				throw new Error(`DOCX relationship target is missing: ${normalized}`);
+			}
+		}
+	}
+}
+
+function validatePackage(pkg: Package): void {
+	for (const part of ["[Content_Types].xml", "word/document.xml"]) {
+		parseXml(pkg[part], part);
+	}
+	for (const [part, bytes] of Object.entries(pkg)) {
+		if (part.endsWith(".xml") || part.endsWith(".rels")) parseXml(bytes, part);
+	}
+	validateRelationships(pkg);
+}
+
+async function load(path: string): Promise<Package> {
+	return unpack(new Uint8Array(await readFile(resolve(path))));
+}
+
+export async function inspectDocx(path: string): Promise<DocxFormatting> {
+	const pkg = await load(path);
+	validatePackage(pkg);
+	return inspectPackage(pkg);
+}
+
+export async function patchDocx(
+	inputPath: string,
+	outputPath: string,
+	patch: DocxPatchSet,
+	dryRun = false,
+): Promise<DocxPatchResult> {
+	const input = resolve(inputPath);
+	const output = resolve(outputPath);
+	if (input === output) throw new Error("DOCX patch output must differ from input");
+	validatePatch(patch);
+	const pkg = await load(input);
+	validatePackage(pkg);
+	const changedParts = applyPatch(pkg, patch);
+	validatePackage(pkg);
+	const formatting = inspectPackage(pkg);
+	validateRequested(formatting, patch);
+	const allParts = Object.keys(pkg).sort();
+	const result = {
+		formatting,
+		changedParts: changedParts.sort(),
+		preservedParts: allParts.filter((part) => !changedParts.includes(part)),
+		written: false,
+	};
+	if (dryRun) return result;
+	const temporary = join(dirname(output), `.${output.split(/[\\/]/).pop()}.${randomUUID()}.tmp`);
+	await mkdir(dirname(output), { recursive: true });
+	try {
+		await writeFile(temporary, zipSync(pkg));
+		await inspectDocx(temporary);
+		await rename(temporary, output);
+		result.written = true;
+		return result;
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}

package/src/index.ts

@@ -0,0 +1,335 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	truncateHead,
+	withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { type DocxPatchSet, inspectDocx, patchDocx } from "./docx.js";
+import { readDocxText, searchDocx, writeDocx } from "./pandoc.js";
+import { readPdfText, renderPdfPages, searchPdf } from "./pdf.js";
+import { commandError, runCommand } from "./process.js";
+
+const docxPatchesSchema = Type.Object(
+	{
+		page: Type.Optional(
+			Type.Object(
+				{
+					width: Type.Optional(Type.Integer({ minimum: 1 })),
+					height: Type.Optional(Type.Integer({ minimum: 1 })),
+					orientation: Type.Optional(StringEnum(["portrait", "landscape"] as const)),
+				},
+				{ additionalProperties: false, minProperties: 1 },
+			),
+		),
+		margins: Type.Optional(
+			Type.Object(
+				{
+					top: Type.Optional(Type.Integer()),
+					bottom: Type.Optional(Type.Integer()),
+					left: Type.Optional(Type.Integer()),
+					right: Type.Optional(Type.Integer()),
+					header: Type.Optional(Type.Integer()),
+					footer: Type.Optional(Type.Integer()),
+					gutter: Type.Optional(Type.Integer()),
+				},
+				{ additionalProperties: false, minProperties: 1 },
+			),
+		),
+		lineNumbering: Type.Optional(
+			Type.Object(
+				{
+					mode: Type.Optional(StringEnum(["off", "continuous", "newPage", "newSection"] as const)),
+					start: Type.Optional(Type.Integer({ minimum: 0 })),
+					count_by: Type.Optional(Type.Integer({ minimum: 1 })),
+				},
+				{ additionalProperties: false, minProperties: 1 },
+			),
+		),
+		pageNumbering: Type.Optional(
+			Type.Object(
+				{
+					start: Type.Optional(Type.Integer({ minimum: 0 })),
+					format: Type.Optional(Type.String({ minLength: 1 })),
+				},
+				{ additionalProperties: false, minProperties: 1 },
+			),
+		),
+		metadata: Type.Optional(
+			Type.Object(
+				{
+					title: Type.Optional(Type.String()),
+					subject: Type.Optional(Type.String()),
+					creator: Type.Optional(Type.String()),
+					keywords: Type.Optional(Type.String()),
+					description: Type.Optional(Type.String()),
+					lastModifiedBy: Type.Optional(Type.String()),
+				},
+				{ additionalProperties: false, minProperties: 1 },
+			),
+		),
+		clearCoreMetadata: Type.Optional(
+			Type.Boolean({
+				description: "Clear common fields in docProps/core.xml; not comment or revision authors",
+			}),
+		),
+	},
+	{ additionalProperties: false, minProperties: 1 },
+);
+
+export const fillerSchema = Type.Object(
+	{
+		format: StringEnum(["docx", "pdf"] as const),
+		action: StringEnum(["read", "search", "write", "patch"] as const),
+		view: Type.Optional(StringEnum(["text", "formatting", "image"] as const)),
+		path: Type.String({ description: "Input document path", minLength: 1 }),
+		output: Type.Optional(
+			Type.String({ description: "Output file or image prefix", minLength: 1 }),
+		),
+		query: Type.Optional(Type.String({ description: "Search query", minLength: 1 })),
+		reference_docx: Type.Optional(
+			Type.String({ description: "Reference DOCX for writes", minLength: 1 }),
+		),
+		patches: Type.Optional(docxPatchesSchema),
+		dry_run: Type.Optional(Type.Boolean({ description: "Validate and report without writing" })),
+		literal: Type.Optional(
+			Type.Boolean({ description: "Treat a PDF search query as literal text" }),
+		),
+		ignore_case: Type.Optional(Type.Boolean({ description: "Ignore case while searching" })),
+		first_page: Type.Optional(Type.Integer({ minimum: 1 })),
+		last_page: Type.Optional(Type.Integer({ minimum: 1 })),
+	},
+	{ additionalProperties: false },
+);
+
+export type FillerInput = Static<typeof fillerSchema>;
+
+type ControlField = Exclude<keyof FillerInput, "format" | "action" | "view" | "path">;
+
+const controlFields: ControlField[] = [
+	"output",
+	"query",
+	"reference_docx",
+	"patches",
+	"dry_run",
+	"literal",
+	"ignore_case",
+	"first_page",
+	"last_page",
+];
+
+export function normalizePath(path: string, cwd: string): string {
+	const withoutAt = path.startsWith("@") ? path.slice(1) : path;
+	if (!withoutAt) throw new Error("Path must not be empty");
+	return resolve(cwd, withoutAt);
+}
+
+function validatePageRange(input: FillerInput): void {
+	if (input.first_page !== undefined && input.first_page < 1) {
+		throw new Error("first_page must be at least 1");
+	}
+	if (input.last_page !== undefined && input.last_page < 1) {
+		throw new Error("last_page must be at least 1");
+	}
+	if (
+		input.first_page !== undefined &&
+		input.last_page !== undefined &&
+		input.first_page > input.last_page
+	) {
+		throw new Error("first_page cannot be greater than last_page");
+	}
+}
+
+function assertParameters(input: FillerInput, allowed: readonly ControlField[]): void {
+	for (const field of controlFields) {
+		if (input[field] !== undefined && !allowed.includes(field)) {
+			throw new Error(`${input.format.toUpperCase()} ${input.action} does not accept ${field}`);
+		}
+	}
+}
+
+function assertSupported(input: FillerInput): void {
+	if (!input.path) throw new Error("path must not be empty");
+	if (input.format === "docx") {
+		if (input.action === "read") {
+			if (input.view === "image") {
+				if (!input.output) throw new Error("DOCX image reads require output");
+				assertParameters(input, ["output", "first_page", "last_page"]);
+				return;
+			}
+			if (input.view !== "text" && input.view !== "formatting") {
+				throw new Error("DOCX read requires view=text, view=formatting, or view=image");
+			}
+			assertParameters(input, []);
+			return;
+		}
+		if (input.action === "search") {
+			if (input.view !== undefined && input.view !== "text") {
+				throw new Error("DOCX search requires view=text or no view");
+			}
+			if (!input.query) throw new Error("DOCX search requires query");
+			assertParameters(input, ["query", "ignore_case"]);
+			return;
+		}
+		if (input.action === "write") {
+			if (input.view !== undefined || !input.output) {
+				throw new Error("DOCX write requires output and does not accept view");
+			}
+			assertParameters(input, ["output", "reference_docx"]);
+			return;
+		}
+		if (input.view !== undefined || !input.output) {
+			throw new Error("DOCX patch requires output and does not accept view");
+		}
+		if (input.patches === undefined) throw new Error("DOCX patch requires patches");
+		assertParameters(input, ["output", "patches", "dry_run"]);
+		return;
+	}
+
+	if (input.action === "write" || input.action === "patch") {
+		throw new Error("PDF write and patch operations are not supported");
+	}
+	if (input.action === "search") {
+		if (input.view !== undefined && input.view !== "text") {
+			throw new Error("PDF search requires view=text or no view");
+		}
+		if (!input.query) throw new Error("PDF search requires query");
+		assertParameters(input, ["query", "literal", "ignore_case", "first_page", "last_page"]);
+		return;
+	}
+	if (input.view !== "text" && input.view !== "image") {
+		throw new Error("PDF read requires view=text or view=image");
+	}
+	if (input.view === "image") {
+		if (!input.output) throw new Error("PDF image reads require output");
+		assertParameters(input, ["output", "first_page", "last_page"]);
+		return;
+	}
+	assertParameters(input, ["first_page", "last_page"]);
+}
+
+export interface FillerResult {
+	text: string;
+	details: Record<string, unknown>;
+}
+
+export async function executeFiller(
+	input: FillerInput,
+	cwd: string,
+	signal?: AbortSignal,
+): Promise<FillerResult> {
+	assertSupported(input);
+	validatePageRange(input);
+	const path = normalizePath(input.path, cwd);
+	const range = { firstPage: input.first_page, lastPage: input.last_page };
+
+	if (input.format === "docx") {
+		if (input.action === "read" && input.view === "formatting") {
+			const formatting = await inspectDocx(path);
+			return { text: JSON.stringify(formatting, null, 2), details: { formatting } };
+		}
+		if (input.action === "read" && input.view === "image") {
+			const output = normalizePath(input.output ?? "", cwd);
+			const temporary = await mkdtemp(join(tmpdir(), "pi-filler-docx-"));
+			try {
+				const converted = await runCommand(
+					"libreoffice",
+					["--headless", "--convert-to", "pdf", "--outdir", temporary, path],
+					{ signal, cwd: temporary },
+				);
+				if (converted.code !== 0) throw commandError(converted, "libreoffice");
+				const pdf = join(temporary, `${basename(path, extname(path))}.pdf`);
+				const result = await withFileMutationQueue(output, () =>
+					renderPdfPages(pdf, output, range, { signal }),
+				);
+				return {
+					text: `Rendered ${result.length} page image${result.length === 1 ? "" : "s"}:\n${result.join("\n")}`,
+					details: { files: result },
+				};
+			} finally {
+				await rm(temporary, { recursive: true, force: true });
+			}
+		}
+		if (input.action === "read") {
+			const result = await readDocxText(path, { signal });
+			return { text: result.text, details: { truncation: result.truncation } };
+		}
+		if (input.action === "search") {
+			const result = await searchDocx(path, input.query ?? "", {
+				ignoreCase: input.ignore_case,
+				signal,
+			});
+			return {
+				text: result.text || "No matches found",
+				details: { matchCount: result.matchCount, truncation: result.truncation },
+			};
+		}
+		if (input.action === "patch") {
+			const output = normalizePath(input.output ?? "", cwd);
+			const result = await withFileMutationQueue(output, () =>
+				patchDocx(path, output, input.patches as DocxPatchSet, input.dry_run),
+			);
+			return {
+				text: JSON.stringify(result, null, 2),
+				details: result as unknown as Record<string, unknown>,
+			};
+		}
+
+		const output = normalizePath(input.output ?? "", cwd);
+		if (output === path) throw new Error("DOCX write output must differ from input");
+		const referenceDocx = input.reference_docx
+			? normalizePath(input.reference_docx, cwd)
+			: undefined;
+		await withFileMutationQueue(output, () =>
+			writeDocx(path, output, { referenceDocx, signal, cwd: dirname(path) }),
+		);
+		return { text: `Wrote ${output}`, details: { output } };
+	}
+
+	if (input.action === "search") {
+		const result = await searchPdf(path, input.query ?? "", {
+			...range,
+			ignoreCase: input.ignore_case,
+			literal: input.literal,
+			signal,
+		});
+		const truncation = truncateHead(result.text);
+		return {
+			text: truncation.truncated
+				? `${truncation.content}\n\n[Search output truncated at ${DEFAULT_MAX_BYTES} bytes]`
+				: truncation.content || "No matches found",
+			details: { matchCount: result.matchCount, truncation },
+		};
+	}
+	if (input.view === "text") {
+		const result = await readPdfText(path, range, { signal });
+		return { text: result.text, details: { truncation: result.truncation } };
+	}
+
+	const output = normalizePath(input.output ?? "", cwd);
+	const result = await withFileMutationQueue(output, () =>
+		renderPdfPages(path, output, range, { signal }),
+	);
+	return {
+		text: `Rendered ${result.length} page image${result.length === 1 ? "" : "s"}:\n${result.join("\n")}`,
+		details: { files: result },
+	};
+}
+
+export default function extension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "filler",
+		label: "Filler",
+		description: "Read, search, inspect, write, or patch DOCX/PDF documents with bounded output.",
+		promptSnippet: "Read, search, inspect, write, or patch a document",
+		parameters: fillerSchema,
+		async execute(_toolCallId, input, signal, _onUpdate, ctx: ExtensionContext) {
+			const result = await executeFiller(input, ctx.cwd, signal);
+			return { content: [{ type: "text", text: result.text }], details: result.details };
+		},
+	});
+}

package/src/pandoc.ts

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { type TruncationResult, truncateHead } from "@earendil-works/pi-coding-agent";
+import { inspectDocx } from "./docx.js";
+import { commandError, type RunCommandOptions, runCommand } from "./process.js";
+
+export interface DocxTextResult {
+	text: string;
+	truncation: TruncationResult;
+}
+
+export interface DocxSearchResult {
+	matchCount: number;
+	text: string;
+	truncation: TruncationResult;
+}
+
+function commandOptions(options: RunCommandOptions | undefined, path: string): RunCommandOptions {
+	return { ...options, cwd: options?.cwd ?? dirname(path) };
+}
+
+async function runPandoc(
+	args: string[],
+	options: RunCommandOptions | undefined,
+	path: string,
+): Promise<Buffer> {
+	const result = await runCommand("pandoc", args, commandOptions(options, path));
+	if (result.code !== 0) throw commandError(result, "pandoc");
+	return result.stdout;
+}
+
+async function extractDocxMarkdown(path: string, options?: RunCommandOptions): Promise<string> {
+	const source = resolve(path);
+	const output = await runPandoc(
+		["--from=docx", "--to=gfm", "--wrap=none", source],
+		options,
+		source,
+	);
+	return output.toString("utf8");
+}
+
+export async function readDocxText(
+	path: string,
+	options?: RunCommandOptions,
+): Promise<DocxTextResult> {
+	const truncation = truncateHead(await extractDocxMarkdown(path, options));
+	return { text: truncation.content, truncation };
+}
+
+export async function searchDocx(
+	path: string,
+	query: string,
+	options: RunCommandOptions & { ignoreCase?: boolean } = {},
+): Promise<DocxSearchResult> {
+	const extracted = await extractDocxMarkdown(path, options);
+	const needle = options.ignoreCase ? query.toLocaleLowerCase() : query;
+	const matches: string[] = [];
+	for (const [index, text] of extracted.split(/\r?\n/).entries()) {
+		const haystack = options.ignoreCase ? text.toLocaleLowerCase() : text;
+		if (haystack.includes(needle)) matches.push(`line ${index + 1}: ${text}`);
+	}
+	const truncation = truncateHead(matches.join("\n"));
+	return { matchCount: matches.length, text: truncation.content, truncation };
+}
+
+export interface WriteDocxOptions extends RunCommandOptions {
+	referenceDocx?: string;
+}
+
+export async function writeDocx(
+	sourcePath: string,
+	outputPath: string,
+	options: WriteDocxOptions = {},
+): Promise<void> {
+	const source = resolve(sourcePath);
+	const output = resolve(outputPath);
+	if (source === output) throw new Error("DOCX write output must differ from input");
+	const temporary = join(
+		dirname(output),
+		`.${output.split(/[\\/]/).pop() ?? "output.docx"}.${randomUUID()}.tmp`,
+	);
+	await mkdir(dirname(output), { recursive: true });
+	const args = ["--from=gfm", "--to=docx", "--output", temporary];
+	if (options.referenceDocx) args.push("--reference-doc", resolve(options.referenceDocx));
+	args.push(source);
+	try {
+		const result = await runCommand("pandoc", args, {
+			...options,
+			cwd: options.cwd ?? dirname(source),
+		});
+		if (result.code !== 0) throw commandError(result, "pandoc");
+		await inspectDocx(temporary);
+		await rename(temporary, output);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}

package/src/pdf.ts

@@ -0,0 +1,154 @@
+import { mkdir, mkdtemp, readdir, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { type TruncationResult, truncateHead } from "@earendil-works/pi-coding-agent";
+import { commandError, type RunCommandOptions, runCommand } from "./process.js";
+
+export interface PageRange {
+	firstPage?: number;
+	lastPage?: number;
+}
+
+export interface PdfTextResult {
+	text: string;
+	truncation: TruncationResult;
+}
+
+export interface PdfSearchResult {
+	matchCount: number;
+	text: string;
+}
+
+const PDFGREP_MAX_PAGE = 2_147_483_647;
+
+function pageArgs(range: PageRange): string[] {
+	const args: string[] = [];
+	if (range.firstPage !== undefined) args.push("-f", String(range.firstPage));
+	if (range.lastPage !== undefined) args.push("-l", String(range.lastPage));
+	return args;
+}
+
+function searchPageArgs(range: PageRange): string[] {
+	if (range.firstPage === undefined && range.lastPage === undefined) return [];
+	const first = range.firstPage ?? 1;
+	const last = range.lastPage ?? PDFGREP_MAX_PAGE;
+	return ["--page-range", first === last ? String(first) : `${first}-${last}`];
+}
+
+function commandOptions(options: RunCommandOptions | undefined, cwd: string): RunCommandOptions {
+	return { ...options, cwd: options?.cwd ?? cwd };
+}
+
+export async function readPdfText(
+	path: string,
+	range: PageRange = {},
+	options?: RunCommandOptions,
+): Promise<PdfTextResult> {
+	const source = resolve(path);
+	const result = await runCommand(
+		"pdftotext",
+		["-layout", ...pageArgs(range), source, "-"],
+		commandOptions(options, dirname(source)),
+	);
+	if (result.code !== 0) throw commandError(result, "pdftotext");
+	const truncation = truncateHead(result.stdout.toString("utf8"));
+	return { text: truncation.content, truncation };
+}
+
+function escapeRegex(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseSearchOutput(output: string): string[] {
+	return output
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => {
+			const match = line.match(/:(\d+):(.*)$/);
+			if (!match) throw new Error(`Unexpected pdfgrep output: ${line}`);
+			return `page ${match[1]}: ${match[2] ?? ""}`;
+		});
+}
+
+export async function searchPdf(
+	path: string,
+	query: string,
+	options: RunCommandOptions & PageRange & { ignoreCase?: boolean; literal?: boolean } = {},
+): Promise<PdfSearchResult> {
+	const source = resolve(path);
+	const args = ["--color", "never", "--with-filename", "--page-number", ...searchPageArgs(options)];
+	if (options.ignoreCase) args.push("--ignore-case");
+	if (options.literal) args.push("--fixed-strings");
+	args.push("--", query, source);
+	const result = await runCommand("pdfgrep", args, commandOptions(options, dirname(source)));
+	if (result.code !== 0 && result.code !== 1) throw commandError(result, "pdfgrep");
+	const matches = parseSearchOutput(result.stdout.toString("utf8"));
+	return { matchCount: matches.length, text: matches.join("\n") };
+}
+
+async function outputPrefix(output: string, sourcePath: string): Promise<string> {
+	const absolute = resolve(output);
+	let isDirectory = output.endsWith("/") || output.endsWith("\\");
+	try {
+		isDirectory = (await stat(absolute)).isDirectory();
+	} catch {
+		// A not-yet-existing path is treated as a prefix unless it ends in a separator.
+	}
+	if (isDirectory) {
+		await mkdir(absolute, { recursive: true });
+		return join(absolute, basename(sourcePath, extname(sourcePath)));
+	}
+	await mkdir(dirname(absolute), { recursive: true });
+	return absolute.replace(/\.png$/i, "");
+}
+
+function generatedPage(name: string, prefixName: string): number | undefined {
+	if (name === `${prefixName}.png`) return 1;
+	const match = name.match(new RegExp(`^${escapeRegex(prefixName)}-(\\d+)\\.png$`));
+	return match ? Number(match[1]) : undefined;
+}
+
+async function generatedPages(directory: string, prefixName: string): Promise<string[]> {
+	return (await readdir(directory))
+		.map((name) => ({ name, page: generatedPage(name, prefixName) }))
+		.filter((entry): entry is { name: string; page: number } => entry.page !== undefined)
+		.sort((a, b) => a.page - b.page)
+		.map(({ name }) => name);
+}
+
+async function clearGenerated(directory: string, prefixName: string): Promise<void> {
+	for (const name of await generatedPages(directory, prefixName)) {
+		await rm(join(directory, name), { force: true });
+	}
+}
+
+export async function renderPdfPages(
+	path: string,
+	output: string,
+	range: PageRange = {},
+	options?: RunCommandOptions,
+): Promise<string[]> {
+	const source = resolve(path);
+	const prefix = await outputPrefix(output, source);
+	const directory = dirname(prefix);
+	const prefixName = basename(prefix);
+	const temporaryDirectory = await mkdtemp(join(directory, `.${prefixName}.`));
+	const temporaryPrefix = join(temporaryDirectory, prefixName);
+	try {
+		const result = await runCommand(
+			"pdftocairo",
+			["-png", ...pageArgs(range), source, temporaryPrefix],
+			commandOptions(options, dirname(source)),
+		);
+		if (result.code !== 0) throw commandError(result, "pdftocairo");
+
+		const names = await generatedPages(temporaryDirectory, prefixName);
+		if (names.length === 0) throw new Error("pdftocairo produced no PNG files");
+		await clearGenerated(directory, prefixName);
+		for (const name of names) {
+			await rename(join(temporaryDirectory, name), join(directory, name));
+		}
+		return names.map((name) => join(directory, name));
+	} finally {
+		await rm(temporaryDirectory, { recursive: true, force: true });
+	}
+}

package/src/process.ts

@@ -0,0 +1,97 @@
+import { execFile } from "node:child_process";
+
+export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+export const DEFAULT_COMMAND_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+
+export interface CommandResult {
+	stdout: Buffer;
+	stderr: Buffer;
+	code: number;
+}
+
+export class MissingExecutableError extends Error {
+	constructor(public readonly executable: string) {
+		super(
+			`Required executable "${executable}" was not found. ` +
+				`Install it and make sure it is available on PATH.`,
+		);
+		this.name = "MissingExecutableError";
+	}
+}
+
+export interface RunCommandOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	maxBufferBytes?: number;
+}
+
+type ExecFailure = Error & {
+	code?: string | number | null;
+	killed?: boolean;
+};
+
+export function runCommand(
+	executable: string,
+	args: readonly string[],
+	options: RunCommandOptions = {},
+): Promise<CommandResult> {
+	return new Promise((resolve, reject) => {
+		execFile(
+			executable,
+			[...args],
+			{
+				cwd: options.cwd,
+				env: options.env,
+				signal: options.signal,
+				timeout: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+				maxBuffer: options.maxBufferBytes ?? DEFAULT_COMMAND_MAX_BUFFER_BYTES,
+				killSignal: "SIGKILL",
+				encoding: null,
+			},
+			(error, stdout, stderr) => {
+				if (!error) {
+					resolve({ stdout, stderr, code: 0 });
+					return;
+				}
+
+				const failure = error as ExecFailure;
+				if (failure.code === "ENOENT") {
+					reject(new MissingExecutableError(executable));
+					return;
+				}
+				if (failure.code === "ABORT_ERR") {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+				if (failure.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+					reject(
+						new Error(
+							`${executable} output exceeded ${options.maxBufferBytes ?? DEFAULT_COMMAND_MAX_BUFFER_BYTES} bytes`,
+						),
+					);
+					return;
+				}
+				if (failure.killed) {
+					reject(
+						new Error(
+							`${executable} timed out after ${options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS}ms`,
+						),
+					);
+					return;
+				}
+				if (typeof failure.code === "number") {
+					resolve({ stdout, stderr, code: failure.code });
+					return;
+				}
+				reject(new Error(`Failed to run ${executable}: ${failure.message}`));
+			},
+		);
+	});
+}
+
+export function commandError(result: CommandResult, executable: string): Error {
+	const message = result.stderr.toString("utf8").trim();
+	return new Error(message || `${executable} exited with code ${result.code}`);
+}