@wonderwhy-er/desktop-commander 0.2.35 → 0.2.36

package/dist/tools/docx/dom.js

@@ -0,0 +1,228 @@
+/**
+ * DOM utilities for DOCX XML manipulation.
+ *
+ * Single Responsibility: XML parsing, navigation, and minimal element
+ * mutation.  No file I/O — every function works on in-memory DOM nodes.
+ *
+ * Uses @xmldom/xmldom for parsing and serialisation so that the
+ * document-order of nodes is always preserved.
+ */
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+// ═══════════════════════════════════════════════════════════════════════
+// XML parse / serialize
+// ═══════════════════════════════════════════════════════════════════════
+export function parseXml(xmlStr) {
+    return new DOMParser().parseFromString(xmlStr, 'application/xml');
+}
+export function serializeXml(doc) {
+    return new XMLSerializer().serializeToString(doc);
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Generic DOM helpers
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Convert any NodeList / HTMLCollection-like object into a real array.
+ */
+export function nodeListToArray(nl) {
+    const arr = [];
+    for (let i = 0; i < nl.length; i++) {
+        const n = nl.item(i);
+        if (n)
+            arr.push(n);
+    }
+    return arr;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Body access
+// ═══════════════════════════════════════════════════════════════════════
+/** Return the single <w:body> element from a parsed document.xml DOM. */
+export function getBody(doc) {
+    const body = doc.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX DOM: missing <w:body>');
+    return body;
+}
+/**
+ * Return ALL direct element children of w:body **in document order**.
+ * Includes w:p, w:tbl, w:sdt, w:sectPr, etc.
+ */
+export function getBodyChildren(body) {
+    const out = [];
+    for (const node of nodeListToArray(body.childNodes)) {
+        if (node.nodeType === 1)
+            out.push(node);
+    }
+    return out;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Body signature
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Build a compact signature string from the body children array.
+ * Maps each node's qualified name to a short local name:
+ *   w:p → p, w:tbl → tbl, w:sdt → sdt, w:sectPr → sectPr, …
+ * Returns e.g. "p,tbl,p,p,sectPr".
+ */
+export function bodySignature(children) {
+    return children
+        .map((ch) => {
+        const name = ch.nodeName;
+        const idx = name.indexOf(':');
+        return idx >= 0 ? name.substring(idx + 1) : name;
+    })
+        .join(',');
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Paragraph text helpers
+// ═══════════════════════════════════════════════════════════════════════
+/** Concatenate text from every <w:t> descendant of a paragraph. */
+export function getParagraphText(p) {
+    const tNodes = p.getElementsByTagName('w:t');
+    let out = '';
+    for (let i = 0; i < tNodes.length; i++) {
+        out += tNodes.item(i)?.textContent ?? '';
+    }
+    return out;
+}
+/** Read the style id from w:pPr/w:pStyle/@w:val, or null if absent. */
+export function getParagraphStyle(p) {
+    for (const child of nodeListToArray(p.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:pPr') {
+            const pPr = child;
+            for (const prChild of nodeListToArray(pPr.childNodes)) {
+                if (prChild.nodeType === 1 && prChild.nodeName === 'w:pStyle') {
+                    return prChild.getAttribute('w:val');
+                }
+            }
+            return null;
+        }
+    }
+    return null;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Minimal text replacement
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Replace the text of a paragraph with minimal DOM changes.
+ * Sets the FIRST w:t to `text`, clears every subsequent w:t.
+ * Sets xml:space="preserve" so leading/trailing spaces survive.
+ * Does NOT recreate runs or remove paragraph properties.
+ */
+export function setParagraphTextMinimal(p, text) {
+    const tNodes = p.getElementsByTagName('w:t');
+    if (tNodes.length === 0)
+        return;
+    const first = tNodes.item(0);
+    first.textContent = text;
+    first.setAttribute('xml:space', 'preserve');
+    for (let i = 1; i < tNodes.length; i++) {
+        tNodes.item(i).textContent = '';
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Run-level formatting helpers
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Ensure a <w:r> element has w:rPr/w:color[@w:val=hex].
+ * Creates w:rPr and w:color if they don't exist.
+ * Only touches the colour — leaves every other run property intact.
+ */
+export function ensureRunColor(run, hex) {
+    const doc = run.ownerDocument;
+    if (!doc)
+        return;
+    let rPr = findDirectChild(run, 'w:rPr');
+    if (!rPr) {
+        rPr = doc.createElement('w:rPr');
+        if (run.firstChild) {
+            run.insertBefore(rPr, run.firstChild);
+        }
+        else {
+            run.appendChild(rPr);
+        }
+    }
+    let colorEl = findDirectChild(rPr, 'w:color');
+    if (!colorEl) {
+        colorEl = doc.createElement('w:color');
+        rPr.appendChild(colorEl);
+    }
+    colorEl.setAttribute('w:val', hex);
+}
+/**
+ * Apply run-level colour to every <w:r> in a paragraph.
+ */
+export function colorParagraphRuns(p, color) {
+    const runs = nodeListToArray(p.getElementsByTagName('w:r'));
+    for (const r of runs) {
+        ensureRunColor(r, color);
+    }
+}
+/**
+ * Apply bold / italic / color to every <w:r> in a paragraph.
+ * Preserves all existing w:rPr children; only modifies specified props.
+ */
+export function styleParagraphRuns(p, style) {
+    const doc = p.ownerDocument;
+    if (!doc)
+        return;
+    const runs = nodeListToArray(p.getElementsByTagName('w:r'));
+    for (const r of runs) {
+        let rPr = findDirectChild(r, 'w:rPr');
+        if (!rPr) {
+            rPr = doc.createElement('w:rPr');
+            if (r.firstChild) {
+                r.insertBefore(rPr, r.firstChild);
+            }
+            else {
+                r.appendChild(rPr);
+            }
+        }
+        if (style.color) {
+            let colorNode = findDirectChild(rPr, 'w:color');
+            if (!colorNode) {
+                colorNode = doc.createElement('w:color');
+                rPr.appendChild(colorNode);
+            }
+            colorNode.setAttribute('w:val', style.color);
+        }
+        if (style.bold !== undefined) {
+            toggleElement(doc, rPr, 'w:b', style.bold);
+        }
+        if (style.italic !== undefined) {
+            toggleElement(doc, rPr, 'w:i', style.italic);
+        }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Counting helpers
+// ═══════════════════════════════════════════════════════════════════════
+/** Count direct w:tbl children of body. */
+export function countTables(children) {
+    return children.filter((ch) => ch.nodeName === 'w:tbl').length;
+}
+/** Count <w:drawing> descendants (rough image count). */
+export function countImages(body) {
+    return body.getElementsByTagName('w:drawing').length;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Private helpers (DRY: used by multiple public functions)
+// ═══════════════════════════════════════════════════════════════════════
+/** Find the first direct child element with the given nodeName. */
+function findDirectChild(parent, nodeName) {
+    for (const child of nodeListToArray(parent.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === nodeName) {
+            return child;
+        }
+    }
+    return null;
+}
+/** Add or remove a simple flag element (e.g. w:b, w:i) inside a parent. */
+function toggleElement(doc, parent, nodeName, enabled) {
+    const existing = findDirectChild(parent, nodeName);
+    if (enabled && !existing) {
+        parent.appendChild(doc.createElement(nodeName));
+    }
+    else if (!enabled && existing) {
+        parent.removeChild(existing);
+    }
+}

package/dist/tools/docx/index.d.ts

@@ -1,14 +1,10 @@
 /**
- * DOCX Operations Library — Public API
- *
- * Re-exports only the symbols that external consumers need.
- * Internal modules (styled-html-parser, validators, converters, etc.)
- * are consumed by sibling files and are NOT part of the public surface.
- *
- * @module docx
+ * DOCX file manipulation tools — barrel exports.
  */
-export { parseDocxToHtml } from './html.js';
-export { createDocxFromHtml } from './builders/html-builder.js';
-export { editDocxWithOperations } from './operations/index.js';
-export type { DocxParseResult, DocxMetadata, DocxImage, DocxSection, DocxOperation, DocxDocumentDefaults, } from './types.js';
-export { DocxError, DocxErrorCode } from './errors.js';
+export { readDocxOutline } from './read.js';
+export { writeDocxPatched } from './write.js';
+export { createDocxNew } from './create.js';
+export type { DocxContentStructure, DocxContentItem, DocxContentParagraph, DocxContentTable, DocxContentImage, } from './types.js';
+export { readDocx, extractTextFromDocx, getDocxMetadata, extractBodyXml } from './read.js';
+export { writeDocx, modifyDocxContent, replaceBodyXml } from './modify.js';
+export type { DocxMetadata, DocxParagraph, DocxRun, DocxModification, ParagraphOutline, ReadDocxResult, WriteDocxStats, WriteDocxResult, BodySnapshot, DocxOp, OpResult, } from './types.js';

package/dist/tools/docx/index.js

@@ -1,16 +1,10 @@
 /**
- * DOCX Operations Library — Public API
- *
- * Re-exports only the symbols that external consumers need.
- * Internal modules (styled-html-parser, validators, converters, etc.)
- * are consumed by sibling files and are NOT part of the public surface.
- *
- * @module docx
+ * DOCX file manipulation tools — barrel exports.
  */
-// ── Reading ─────────────────────────────────────────────────────────────────
-export { parseDocxToHtml } from './html.js';
-// ── Writing / Editing ───────────────────────────────────────────────────────
-export { createDocxFromHtml } from './builders/html-builder.js';
-export { editDocxWithOperations } from './operations/index.js';
-// ── Errors ──────────────────────────────────────────────────────────────────
-export { DocxError, DocxErrorCode } from './errors.js';
+// Patch-based tools (read_docx / write_docx)
+export { readDocxOutline } from './read.js';
+export { writeDocxPatched } from './write.js';
+export { createDocxNew } from './create.js';
+// Legacy functions (used by read_file, write_file, edit_block handlers)
+export { readDocx, extractTextFromDocx, getDocxMetadata, extractBodyXml } from './read.js';
+export { writeDocx, modifyDocxContent, replaceBodyXml } from './modify.js';

package/dist/tools/docx/modify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Legacy DOCX modification operations.
+ *
+ * These functions support the older write_file / edit_block paths that
+ * modify DOCX via simple operations (replace, insert, delete, style).
+ * They are distinct from the new patch-based writeDocxPatched pipeline.
+ *
+ * Single Responsibility: create / modify DOCX content using the legacy
+ * DocxModification interface.  Delegates XML parsing and element
+ * manipulation to the shared dom.ts module.
+ */
+import type { DocxModification } from './types.js';
+/**
+ * Open an existing DOCX, apply an ordered list of modifications to
+ * word/document.xml, and write the result to outputPath.
+ * Every other file in the ZIP (styles, images, rels, …) is preserved.
+ */
+export declare function modifyDocxContent(inputPath: string, outputPath: string, modifications: DocxModification[]): Promise<void>;
+/**
+ * Replace the entire w:body content of a DOCX with new body XML.
+ * Used by the body-XML replacement mode of write_file.
+ */
+export declare function replaceBodyXml(inputPath: string, outputPath: string, newBodyXml: string): Promise<void>;
+/**
+ * Create a brand-new minimal DOCX from a plain-text string.
+ * Double-newlines are treated as paragraph separators.
+ */
+export declare function writeDocx(outputPath: string, content: string | DocxModification[]): Promise<void>;

package/dist/tools/docx/modify.js

@@ -0,0 +1,271 @@
+/**
+ * Legacy DOCX modification operations.
+ *
+ * These functions support the older write_file / edit_block paths that
+ * modify DOCX via simple operations (replace, insert, delete, style).
+ * They are distinct from the new patch-based writeDocxPatched pipeline.
+ *
+ * Single Responsibility: create / modify DOCX content using the legacy
+ * DocxModification interface.  Delegates XML parsing and element
+ * manipulation to the shared dom.ts module.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import PizZip from 'pizzip';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { nodeListToArray, getParagraphText, setParagraphTextMinimal, colorParagraphRuns, styleParagraphRuns, } from './dom.js';
+// ═══════════════════════════════════════════════════════════════════════
+// Helpers (private to this module)
+// ═══════════════════════════════════════════════════════════════════════
+/** Get all direct w:p children of body in document order. */
+function getParagraphs(body) {
+    const paragraphs = [];
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:p') {
+            paragraphs.push(child);
+        }
+    }
+    return paragraphs;
+}
+/** Parse DOCX and return { zip, dom, body }. */
+function parseDocument(inputBuf) {
+    const zip = new PizZip(inputBuf);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const dom = new DOMParser().parseFromString(docFile.asText(), 'application/xml');
+    const body = dom.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX: missing w:body');
+    return { zip, dom, body };
+}
+// ═══════════════════════════════════════════════════════════════════════
+// modifyDocxContent — apply legacy modifications
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Open an existing DOCX, apply an ordered list of modifications to
+ * word/document.xml, and write the result to outputPath.
+ * Every other file in the ZIP (styles, images, rels, …) is preserved.
+ */
+export async function modifyDocxContent(inputPath, outputPath, modifications) {
+    const inputBuf = await fs.readFile(inputPath);
+    const { zip, dom, body } = parseDocument(inputBuf);
+    for (const mod of modifications) {
+        switch (mod.type) {
+            case 'replace':
+                applyReplace(body, mod);
+                break;
+            case 'insert':
+                applyInsert(body, mod);
+                break;
+            case 'delete':
+                applyDelete(body, mod);
+                break;
+            case 'style':
+                applyStyle(body, mod);
+                break;
+        }
+    }
+    const outXml = new XMLSerializer().serializeToString(dom);
+    zip.file('word/document.xml', outXml);
+    const outBuf = zip.generate({ type: 'nodebuffer' });
+    await fs.writeFile(outputPath, outBuf);
+}
+// ═══════════════════════════════════════════════════════════════════════
+// replaceBodyXml — wholesale body replacement
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Replace the entire w:body content of a DOCX with new body XML.
+ * Used by the body-XML replacement mode of write_file.
+ */
+export async function replaceBodyXml(inputPath, outputPath, newBodyXml) {
+    const tempDir = os.tmpdir();
+    const tempDocxPath = path.join(tempDir, `docx_temp_${Date.now()}_${Math.random().toString(36).substring(7)}.docx`);
+    const tempXmlPath = path.join(tempDir, `docx_dom_${Date.now()}_${Math.random().toString(36).substring(7)}.xml`);
+    try {
+        const inputBuf = await fs.readFile(inputPath);
+        await fs.writeFile(tempDocxPath, inputBuf);
+        const { zip, dom, body } = parseDocument(inputBuf);
+        await fs.writeFile(tempXmlPath, zip.file('word/document.xml').asText());
+        // Parse the new body XML
+        const newBodyDom = new DOMParser().parseFromString(`<root>${newBodyXml}</root>`, 'application/xml');
+        const newBodyElement = newBodyDom.documentElement.firstChild;
+        if (!newBodyElement || newBodyElement.nodeName !== 'w:body') {
+            throw new Error('Invalid body XML: must start with <w:body>');
+        }
+        // Import children from new body into original document
+        const doc = body.ownerDocument;
+        if (!doc)
+            throw new Error('Document owner not found');
+        while (body.firstChild)
+            body.removeChild(body.firstChild);
+        for (const child of nodeListToArray(newBodyElement.childNodes)) {
+            body.appendChild(doc.importNode(child, true));
+        }
+        const outXml = new XMLSerializer().serializeToString(dom);
+        zip.file('word/document.xml', outXml);
+        const outBuf = zip.generate({ type: 'nodebuffer' });
+        await fs.writeFile(outputPath, outBuf);
+    }
+    finally {
+        try {
+            await fs.unlink(tempDocxPath);
+        }
+        catch { /* ignore */ }
+        try {
+            await fs.unlink(tempXmlPath);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// writeDocx — create minimal DOCX from plain text
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Create a brand-new minimal DOCX from a plain-text string.
+ * Double-newlines are treated as paragraph separators.
+ */
+export async function writeDocx(outputPath, content) {
+    if (typeof content !== 'string') {
+        throw new Error('Modifications require an existing DOCX file. Use modifyDocxContent() instead.');
+    }
+    const zip = new PizZip();
+    const escaped = (s) => s.replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+    const docXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:body>
+${content
+        .split('\n\n')
+        .map((para) => `    <w:p>
+      <w:r>
+        <w:t>${escaped(para)}</w:t>
+      </w:r>
+    </w:p>`)
+        .join('\n')}
+  </w:body>
+</w:document>`;
+    zip.file('word/document.xml', docXml);
+    zip.file('[Content_Types].xml', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+</Types>`);
+    zip.folder('_rels')?.file('.rels', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>`);
+    zip.folder('word')?.folder('_rels')?.file('document.xml.rels', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+</Relationships>`);
+    const outBuf = zip.generate({ type: 'nodebuffer' });
+    await fs.writeFile(outputPath, outBuf);
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Private modification appliers (SRP: one function per modification type)
+// ═══════════════════════════════════════════════════════════════════════
+function applyReplace(body, mod) {
+    if (mod.findText === undefined)
+        return;
+    const target = mod.findText.trim();
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1 || child.nodeName !== 'w:p')
+            continue;
+        if (getParagraphText(child).trim() !== target)
+            continue;
+        if (mod.replaceText !== undefined) {
+            setParagraphTextMinimal(child, mod.replaceText);
+        }
+        if (mod.style) {
+            if (mod.style.color)
+                colorParagraphRuns(child, mod.style.color);
+            if (mod.style.bold !== undefined || mod.style.italic !== undefined) {
+                styleParagraphRuns(child, mod.style);
+            }
+        }
+        break; // first match only
+    }
+}
+function applyInsert(body, mod) {
+    if (mod.paragraphIndex === undefined || mod.insertText === undefined)
+        return;
+    const doc = body.ownerDocument;
+    if (!doc)
+        return;
+    const newP = doc.createElement('w:p');
+    const newR = doc.createElement('w:r');
+    const newT = doc.createElement('w:t');
+    newT.textContent = mod.insertText;
+    newR.appendChild(newT);
+    newP.appendChild(newR);
+    const paragraphs = getParagraphs(body);
+    const idx = mod.paragraphIndex < 0
+        ? paragraphs.length + mod.paragraphIndex + 1
+        : mod.paragraphIndex;
+    if (idx < 0 || idx > paragraphs.length)
+        return;
+    if (idx === paragraphs.length) {
+        body.appendChild(newP);
+    }
+    else {
+        let current = 0;
+        for (const child of nodeListToArray(body.childNodes)) {
+            if (child.nodeType !== 1 || child.nodeName !== 'w:p')
+                continue;
+            if (current === idx) {
+                body.insertBefore(newP, child);
+                break;
+            }
+            current++;
+        }
+    }
+}
+function applyDelete(body, mod) {
+    if (mod.paragraphIndex === undefined)
+        return;
+    const paragraphs = getParagraphs(body);
+    const idx = mod.paragraphIndex < 0
+        ? paragraphs.length + mod.paragraphIndex
+        : mod.paragraphIndex;
+    if (idx < 0 || idx >= paragraphs.length)
+        return;
+    let current = 0;
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1 || child.nodeName !== 'w:p')
+            continue;
+        if (current === idx) {
+            body.removeChild(child);
+            break;
+        }
+        current++;
+    }
+}
+function applyStyle(body, mod) {
+    if (mod.paragraphIndex === undefined || !mod.style)
+        return;
+    const paragraphs = getParagraphs(body);
+    const idx = mod.paragraphIndex < 0
+        ? paragraphs.length + mod.paragraphIndex
+        : mod.paragraphIndex;
+    if (idx < 0 || idx >= paragraphs.length)
+        return;
+    let current = 0;
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1 || child.nodeName !== 'w:p')
+            continue;
+        if (current === idx) {
+            if (mod.style.color)
+                colorParagraphRuns(child, mod.style.color);
+            if (mod.style.bold !== undefined || mod.style.italic !== undefined) {
+                styleParagraphRuns(child, mod.style);
+            }
+            break;
+        }
+        current++;
+    }
+}

package/dist/tools/docx/ops/delete-paragraph-at-body-index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Op: delete_paragraph_at_body_index
+ *
+ * Remove the w:p element at the given bodyChildIndex.
+ * Skips if the child is not a w:p.
+ *
+ * NOTE: This is a structural op — it decreases bodyChildCount by 1.
+ * The orchestrator must account for this when validating invariants.
+ */
+import type { DeleteParagraphAtBodyIndexOp, OpResult } from '../types.js';
+export declare function applyDeleteParagraphAtBodyIndex(body: Element, op: DeleteParagraphAtBodyIndexOp): OpResult;

package/dist/tools/docx/ops/delete-paragraph-at-body-index.js

@@ -0,0 +1,23 @@
+/**
+ * Op: delete_paragraph_at_body_index
+ *
+ * Remove the w:p element at the given bodyChildIndex.
+ * Skips if the child is not a w:p.
+ *
+ * NOTE: This is a structural op — it decreases bodyChildCount by 1.
+ * The orchestrator must account for this when validating invariants.
+ */
+import { getBodyChildren } from '../dom.js';
+export function applyDeleteParagraphAtBodyIndex(body, op) {
+    const children = getBodyChildren(body);
+    const idx = op.bodyChildIndex;
+    if (idx < 0 || idx >= children.length) {
+        return { op, status: 'skipped', matched: 0, reason: 'index_out_of_range' };
+    }
+    const child = children[idx];
+    if (child.nodeName !== 'w:p') {
+        return { op, status: 'skipped', matched: 0, reason: 'not_a_paragraph' };
+    }
+    body.removeChild(child);
+    return { op, status: 'applied', matched: 1 };
+}

package/dist/tools/docx/ops/header-replace-text-exact.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Op: header_replace_text_exact
+ *
+ * Find ALL header XML files (word/header1.xml, header2.xml, …)
+ * in the ZIP, locate the first paragraph matching exact trimmed text,
+ * and replace its text minimally.
+ *
+ * This op modifies header XML files inside the ZIP — not document.xml body.
+ * It receives the PizZip instance from the orchestrator.
+ */
+import PizZip from 'pizzip';
+import type { HeaderReplaceTextExactOp, OpResult } from '../types.js';
+export declare function applyHeaderReplaceTextExact(_body: Element, op: HeaderReplaceTextExactOp, zip: PizZip): OpResult;