@wonderwhy-er/desktop-commander 0.2.33 → 0.2.35

package/dist/tools/docx/operations/handlers/index.js

@@ -0,0 +1,152 @@
+/**
+ * DOCX Operation Handlers
+ *
+ * Pure functions: HTML in → modified HTML out.
+ * Each handler corresponds to one DocxOperation type.
+ *
+ * @module docx/operations/handlers
+ */
+import { DocxError, DocxErrorCode } from '../../errors.js';
+import { markdownToHtml, markdownTableToHtml, buildMarkdownTableFromRows, } from '../../converters/markdown-to-html.js';
+import { appendHtml, insertHtml, replaceHtml, updateHtml } from '../html-manipulator.js';
+import { escapeHtmlAttribute, escapeRegExp } from '../../utils/escaping.js';
+import { isUrl, isDataUrl, resolveImagePath } from '../../utils/paths.js';
+import { validateImageDimensions } from '../../validators.js';
+// ─── Text Operations ─────────────────────────────────────────────────────────
+/**
+ * Replace text in HTML while protecting base64 data URLs and other attribute values.
+ *
+ * Strategy: Temporarily extract `<img>` tags (which contain huge base64 data URLs)
+ * and replace them with placeholders, perform the text replacement,
+ * then restore the original `<img>` tags. This prevents the regex from
+ * accidentally matching / corrupting base64 image data.
+ */
+export function handleReplaceText(html, search, replace, matchCase = false, global = true) {
+    if (!search?.trim())
+        return html;
+    // Extract and protect all <img> tags from text replacement
+    const imgPlaceholders = [];
+    const protectedHtml = html.replace(/<img\s[^>]*>/gi, (match) => {
+        imgPlaceholders.push(match);
+        return `\x00IMG_PLACEHOLDER_${imgPlaceholders.length - 1}\x00`;
+    });
+    // Perform the text replacement on the protected HTML
+    const flags = matchCase ? (global ? 'g' : '') : global ? 'gi' : 'i';
+    let result = protectedHtml.replace(new RegExp(escapeRegExp(search), flags), replace);
+    // Restore the original <img> tags
+    for (let i = 0; i < imgPlaceholders.length; i++) {
+        result = result.replace(`\x00IMG_PLACEHOLDER_${i}\x00`, imgPlaceholders[i]);
+    }
+    return result;
+}
+// ─── HTML / Markdown Append & Insert ─────────────────────────────────────────
+export function handleAppendMarkdown(html, markdown) {
+    if (!markdown?.trim())
+        return html;
+    const converted = markdownToHtml(markdown);
+    return converted ? appendHtml(html, converted) : html;
+}
+export function handleAppendHtml(html, content) {
+    return appendHtml(html, content);
+}
+export function handleInsertHtml(html, content, selector, position = 'after') {
+    return insertHtml(html, content, selector, position);
+}
+export function handleReplaceHtml(html, selector, content, replaceAll = false) {
+    return replaceHtml(html, selector, content, replaceAll);
+}
+export function handleUpdateHtml(html, selector, content, attributes, updateAll = false) {
+    return updateHtml(html, selector, content, attributes, updateAll);
+}
+// ─── Table Insertion ─────────────────────────────────────────────────────────
+/**
+ * Insert a table from markdown or a rows array.
+ * If a selector is given, the table is placed relative to that element;
+ * otherwise it is appended to the end of the document.
+ */
+export function handleInsertTable(html, markdownTable, rows, selector, position = 'after') {
+    let tableHtml = '';
+    if (markdownTable?.trim()) {
+        tableHtml = markdownTableToHtml(markdownTable);
+    }
+    else if (rows?.length) {
+        const md = buildMarkdownTableFromRows(rows);
+        if (md)
+            tableHtml = markdownTableToHtml(md);
+    }
+    if (!tableHtml)
+        return html;
+    return selector?.trim()
+        ? insertHtml(html, tableHtml, selector, position)
+        : appendHtml(html, tableHtml);
+}
+// ─── Image Insertion ─────────────────────────────────────────────────────────
+/**
+ * Insert an image into the document.
+ *
+ * By the time this handler runs, local file paths should already be converted
+ * to base64 data URLs by `preprocessOperations()` in `operations/index.ts`.
+ * html-to-docx only supports base64 data URLs and HTTP URLs.
+ */
+export function handleInsertImage(html, imagePath, altText = '', width, height, baseDir, selector, position = 'after') {
+    if (!imagePath?.trim())
+        return html;
+    if (width !== undefined || height !== undefined)
+        validateImageDimensions(width, height);
+    const trimmedPath = imagePath.trim();
+    let imageSrc;
+    if (isDataUrl(trimmedPath) || isUrl(trimmedPath)) {
+        imageSrc = trimmedPath;
+    }
+    else {
+        // Fallback: should not normally occur after preprocessing
+        const resolved = resolveImagePath(trimmedPath, baseDir).replace(/\\/g, '/');
+        imageSrc = resolved.startsWith('/') ? `file://${resolved}` : `file:///${resolved}`;
+    }
+    // Build img attributes
+    const attrs = [`src="${escapeHtmlAttribute(imageSrc)}"`];
+    if (altText?.trim())
+        attrs.push(`alt="${escapeHtmlAttribute(altText.trim())}"`);
+    // Add dimensions as both attributes and inline style (for compatibility)
+    const styles = [];
+    if (width && width > 0) {
+        attrs.push(`width="${width}"`);
+        styles.push(`width:${width}px`);
+    }
+    if (height && height > 0) {
+        attrs.push(`height="${height}"`);
+        styles.push(`height:${height}px`);
+    }
+    if (styles.length > 0)
+        attrs.push(`style="${styles.join('; ')}"`);
+    const imgTag = `<p><img ${attrs.join(' ')} /></p>`;
+    return selector?.trim()
+        ? insertHtml(html, imgTag, selector, position)
+        : appendHtml(html, imgTag);
+}
+// ─── Operation Router ────────────────────────────────────────────────────────
+/** Apply a single DocxOperation to HTML content, routing to the correct handler. */
+export function applyOperation(html, operation, baseDir) {
+    switch (operation.type) {
+        case 'replaceText':
+            return handleReplaceText(html, operation.search, operation.replace, operation.matchCase ?? false, operation.global ?? true);
+        case 'appendMarkdown':
+            return handleAppendMarkdown(html, operation.markdown);
+        case 'appendHtml':
+            return handleAppendHtml(html, operation.html);
+        case 'insertHtml':
+            return handleInsertHtml(html, operation.html, operation.selector, operation.position ?? 'after');
+        case 'replaceHtml':
+            return handleReplaceHtml(html, operation.selector, operation.html, operation.replaceAll ?? false);
+        case 'updateHtml':
+            return handleUpdateHtml(html, operation.selector, operation.html, operation.attributes, operation.updateAll ?? false);
+        case 'insertTable':
+            return handleInsertTable(html, operation.markdownTable, operation.rows, operation.selector, operation.position ?? 'after');
+        case 'insertImage':
+            return handleInsertImage(html, operation.imagePath, operation.altText, operation.width, operation.height, baseDir, operation.selector, operation.position ?? 'after');
+        default: {
+            const unknownOp = operation;
+            throw new DocxError(`Unknown operation type: ${unknownOp.type}`, DocxErrorCode.UNKNOWN_OPERATION, { operation: unknownOp });
+        }
+    }
+}

package/dist/tools/docx/operations/html-manipulator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTML DOM Manipulation
+ *
+ * DOM-based insert / append / replace / update for HTML content.
+ * Uses @xmldom/xmldom as the parser (not a browser DOMParser).
+ *
+ * IMPORTANT: All public functions use `Base64Guard` to protect base64 data URLs
+ * from corruption during xmldom parse/serialize cycles. Without this, images
+ * (which are embedded as long `data:image/...;base64,...` strings in `src` attributes)
+ * can be lost or mangled by the XML serializer.
+ *
+ * @module docx/operations/html-manipulator
+ */
+/** Append HTML content to the end of the document body. */
+export declare function appendHtml(html: string, content: string): string;
+/**
+ * Insert HTML content at a specific position relative to a selector target.
+ * If no selector is given, appends to the root element.
+ */
+export declare function insertHtml(html: string, content: string, selector?: string, position?: 'before' | 'after' | 'inside'): string;
+/** Replace matched elements with new HTML content. */
+export declare function replaceHtml(html: string, selector: string, content: string, replaceAll?: boolean): string;
+/** Update matched elements' content and/or attributes. */
+export declare function updateHtml(html: string, selector: string, content?: string, attributes?: Record<string, string>, updateAll?: boolean): string;

package/dist/tools/docx/operations/html-manipulator.js

@@ -0,0 +1,352 @@
+/**
+ * HTML DOM Manipulation
+ *
+ * DOM-based insert / append / replace / update for HTML content.
+ * Uses @xmldom/xmldom as the parser (not a browser DOMParser).
+ *
+ * IMPORTANT: All public functions use `Base64Guard` to protect base64 data URLs
+ * from corruption during xmldom parse/serialize cycles. Without this, images
+ * (which are embedded as long `data:image/...;base64,...` strings in `src` attributes)
+ * can be lost or mangled by the XML serializer.
+ *
+ * @module docx/operations/html-manipulator
+ */
+import { createRequire } from 'module';
+import { DocxError, DocxErrorCode } from '../errors.js';
+const require = createRequire(import.meta.url);
+const { DOMParser, XMLSerializer } = require('@xmldom/xmldom');
+// ─── Selector Patterns (pre-compiled) ────────────────────────────────────────
+const RE_CONTAINS = /^([a-zA-Z][a-zA-Z0-9]*)?:contains\((.+)\)$/i;
+const RE_NTH_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):nth-of-type\((\d+)\)$/i;
+const RE_FIRST_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):first-of-type$/i;
+const RE_LAST_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):last-of-type$/i;
+// ─── Base64 Data URL Protection ──────────────────────────────────────────────
+/**
+ * Protects base64 data URLs from corruption during xmldom parse/serialize.
+ *
+ * Problem: xmldom's DOMParser + XMLSerializer can mangle very long attribute
+ * values (base64 image data). Symptoms range from silent truncation to dropped
+ * `<img>` elements.
+ *
+ * Solution: Before DOM operations, replace all `data:…` URLs in `src` attributes
+ * with short placeholder URNs. After serialization, restore the originals.
+ * This keeps the DOM tree lightweight and avoids serializer issues.
+ */
+class Base64Guard {
+    constructor() {
+        this.store = [];
+    }
+    /** Replace all data: URLs in src attributes with short placeholders. */
+    protect(html) {
+        if (!html.includes('data:'))
+            return html; // Fast path: no data URLs
+        return html.replace(/\bsrc="(data:[^"]+)"/g, (_, dataUrl) => {
+            const index = this.store.length;
+            this.store.push(dataUrl);
+            return `src="urn:b64:${index}"`;
+        });
+    }
+    /** Restore original data: URLs from placeholders. */
+    restore(html) {
+        if (this.store.length === 0)
+            return html; // Fast path: nothing to restore
+        let result = html;
+        // Use split/join to avoid $-pattern issues in String.replace
+        for (let i = 0; i < this.store.length; i++) {
+            result = result.split(`urn:b64:${i}`).join(this.store[i]);
+        }
+        return result;
+    }
+}
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+/** Re-throw any non-DocxError as a DocxError. */
+function rethrowAsDocxError(error, message, context) {
+    if (error instanceof DocxError)
+        throw error;
+    throw new DocxError(`${message}: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED, context);
+}
+/**
+ * Parse HTML string into a DOM Document.
+ *
+ * @xmldom/xmldom is an XML parser — it does NOT auto-create `<html>/<body>` wrappers
+ * like a browser would. We always ensure a proper structure so that
+ * `getElementsByTagName('body')` works reliably.
+ */
+function parseHtml(html) {
+    try {
+        let htmlToParse = html;
+        const lower = html.toLowerCase();
+        if (!lower.includes('<body'))
+            htmlToParse = `<html><body>${html}</body></html>`;
+        else if (!lower.includes('<html'))
+            htmlToParse = `<html>${html}</html>`;
+        const doc = new DOMParser().parseFromString(htmlToParse, 'text/html');
+        const parserErrors = doc.getElementsByTagName('parsererror');
+        if (parserErrors.length > 0) {
+            throw new DocxError('Failed to parse HTML: invalid structure', DocxErrorCode.OPERATION_FAILED, { htmlSnippet: html.substring(0, 100) });
+        }
+        return doc;
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to parse HTML', { htmlSnippet: html.substring(0, 100) });
+    }
+}
+/**
+ * Serialize a DOM Document back to an HTML string.
+ * Returns only the inner content of `<body>` (no wrapper tags) because we
+ * added those in `parseHtml` for xmldom compatibility.
+ */
+function serializeHtml(doc) {
+    try {
+        const serializer = new XMLSerializer();
+        const body = doc.getElementsByTagName('body')[0];
+        if (body) {
+            let content = '';
+            for (let i = 0; i < body.childNodes.length; i++) {
+                content += serializer.serializeToString(body.childNodes[i]);
+            }
+            return content;
+        }
+        return doc.documentElement ? serializer.serializeToString(doc.documentElement) : '';
+    }
+    catch (error) {
+        throw new DocxError(`Failed to serialize HTML: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED);
+    }
+}
+/** Get the root element (body or documentElement) for querying. */
+function getRootElement(doc) {
+    return doc.getElementsByTagName('body')[0] || doc.documentElement;
+}
+/** Clone nodes from one document into another. */
+function cloneNodesToDocument(sourceNodes, targetDoc) {
+    const nodes = [];
+    for (let i = 0; i < sourceNodes.length; i++) {
+        nodes.push(targetDoc.importNode(sourceNodes[i], true));
+    }
+    return nodes;
+}
+// ─── CSS-like Selector Engine ────────────────────────────────────────────────
+/**
+ * Find elements using an extended CSS-like selector.
+ *
+ * Supported:
+ *   `#id`, `.class`, `tag`,
+ *   `tag:contains(text)`, `:contains(text)`,
+ *   `tag:nth-of-type(N)`, `tag:first-of-type`, `tag:last-of-type`
+ */
+function querySelectorAll(doc, selector) {
+    const s = selector?.trim();
+    if (!s)
+        return [];
+    const root = getRootElement(doc);
+    const elements = [];
+    try {
+        // #id
+        if (s.startsWith('#')) {
+            const el = doc.getElementById(s.substring(1));
+            if (el)
+                elements.push(el);
+            return elements;
+        }
+        // .class
+        if (s.startsWith('.')) {
+            const found = root.getElementsByClassName(s.substring(1));
+            for (let i = 0; i < found.length; i++)
+                elements.push(found[i]);
+            return elements;
+        }
+        // tag:contains(text)
+        const containsMatch = s.match(RE_CONTAINS);
+        if (containsMatch) {
+            const tag = containsMatch[1] || '*';
+            const needle = containsMatch[2].trim().toLowerCase();
+            const candidates = root.getElementsByTagName(tag);
+            for (let i = 0; i < candidates.length; i++) {
+                if ((candidates[i].textContent || '').toLowerCase().includes(needle)) {
+                    elements.push(candidates[i]);
+                }
+            }
+            return elements;
+        }
+        // tag:nth-of-type(N)
+        const nthMatch = s.match(RE_NTH_OF_TYPE);
+        if (nthMatch) {
+            const n = parseInt(nthMatch[2], 10);
+            const found = root.getElementsByTagName(nthMatch[1]);
+            if (n >= 1 && n <= found.length)
+                elements.push(found[n - 1]);
+            return elements;
+        }
+        // tag:first-of-type
+        const firstMatch = s.match(RE_FIRST_OF_TYPE);
+        if (firstMatch) {
+            const found = root.getElementsByTagName(firstMatch[1]);
+            if (found.length > 0)
+                elements.push(found[0]);
+            return elements;
+        }
+        // tag:last-of-type
+        const lastMatch = s.match(RE_LAST_OF_TYPE);
+        if (lastMatch) {
+            const found = root.getElementsByTagName(lastMatch[1]);
+            if (found.length > 0)
+                elements.push(found[found.length - 1]);
+            return elements;
+        }
+        // Plain tag name (fallback)
+        const found = root.getElementsByTagName(s);
+        for (let i = 0; i < found.length; i++)
+            elements.push(found[i]);
+    }
+    catch (error) {
+        throw new DocxError(`Failed to query selector "${selector}": ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED);
+    }
+    return elements;
+}
+// ─── DOM Position Helper ─────────────────────────────────────────────────────
+/** Insert `node` relative to `target` at the given `position`. */
+function insertAtPosition(node, target, position) {
+    switch (position) {
+        case 'before':
+            target.parentNode?.insertBefore(node, target);
+            break;
+        case 'inside':
+            target.appendChild(node);
+            break;
+        case 'after':
+        default:
+            if (target.nextSibling)
+                target.parentNode?.insertBefore(node, target.nextSibling);
+            else
+                target.parentNode?.appendChild(node);
+            break;
+    }
+}
+// ─── Public Operations ───────────────────────────────────────────────────────
+// All public functions use Base64Guard to protect image data URLs from
+// corruption during the xmldom parse → manipulate → serialize cycle.
+/** Append HTML content to the end of the document body. */
+export function appendHtml(html, content) {
+    if (!content?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const body = doc.getElementsByTagName('body')[0];
+        if (!body)
+            return html.trim() + '\n' + content.trim();
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        for (const node of cloneNodesToDocument(contentRoot.childNodes, doc)) {
+            body.appendChild(node);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to append HTML');
+    }
+}
+/**
+ * Insert HTML content at a specific position relative to a selector target.
+ * If no selector is given, appends to the root element.
+ */
+export function insertHtml(html, content, selector, position = 'after') {
+    if (!content?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const root = getRootElement(doc);
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        const nodesToInsert = cloneNodesToDocument(contentRoot.childNodes, doc);
+        if (!selector) {
+            for (const node of nodesToInsert)
+                root.appendChild(node);
+            return guard.restore(serializeHtml(doc));
+        }
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        // Insert at FIRST match only to prevent duplication
+        const target = targets[0];
+        for (const node of nodesToInsert) {
+            insertAtPosition(node.cloneNode(true), target, position);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to insert HTML', { selector, position });
+    }
+}
+/** Replace matched elements with new HTML content. */
+export function replaceHtml(html, selector, content, replaceAll = false) {
+    if (!selector?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        const replaceNodes = cloneNodesToDocument(contentRoot.childNodes, doc);
+        for (const target of replaceAll ? targets : [targets[0]]) {
+            const parent = target.parentNode;
+            if (!parent)
+                continue;
+            for (const node of replaceNodes)
+                parent.insertBefore(node.cloneNode(true), target);
+            parent.removeChild(target);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to replace HTML', { selector, replaceAll });
+    }
+}
+/** Update matched elements' content and/or attributes. */
+export function updateHtml(html, selector, content, attributes, updateAll = false) {
+    if (!selector?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = content !== undefined ? guard.protect(content) : undefined;
+    try {
+        const doc = parseHtml(safeHtml);
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        for (const target of updateAll ? targets : [targets[0]]) {
+            // Replace innerHTML via DOM methods (xmldom doesn't support .innerHTML setter)
+            if (safeContent !== undefined) {
+                while (target.firstChild)
+                    target.removeChild(target.firstChild);
+                const contentDoc = parseHtml(safeContent);
+                const contentRoot = getRootElement(contentDoc);
+                for (const child of cloneNodesToDocument(contentRoot.childNodes, doc)) {
+                    target.appendChild(child);
+                }
+            }
+            if (attributes) {
+                for (const [key, value] of Object.entries(attributes)) {
+                    target.setAttribute(key, value);
+                }
+            }
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to update HTML', { selector, updateAll });
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * DOCX Editing Operations
+ *
+ * Reads DOCX → HTML (via direct XML parser or mammoth fallback),
+ * applies a sequence of operations to the HTML DOM,
+ * then converts the modified HTML → DOCX (html-to-docx).
+ *
+ * @module docx/operations
+ */
+import type { DocxEditOptions, DocxOperation } from '../types.js';
+/**
+ * Apply a sequence of edit operations to a DOCX file and return the modified DOCX as a Buffer.
+ */
+export declare function editDocxWithOperations(docxPath: string, operations: DocxOperation[], options?: DocxEditOptions): Promise<Buffer>;

package/dist/tools/docx/operations/index.js

@@ -0,0 +1,61 @@
+/**
+ * DOCX Editing Operations
+ *
+ * Reads DOCX → HTML (via direct XML parser or mammoth fallback),
+ * applies a sequence of operations to the HTML DOM,
+ * then converts the modified HTML → DOCX (html-to-docx).
+ *
+ * @module docx/operations
+ */
+import path from 'path';
+import { DocxError, DocxErrorCode, withErrorContext } from '../errors.js';
+import { parseDocxToHtml } from '../html.js';
+import { createDocxFromHtml } from '../builders/html-builder.js';
+import { DEFAULT_CONVERSION_OPTIONS } from '../constants.js';
+import { DocxOperationSchema } from '../../schemas.js';
+import { validateDocxPath, validateOperations } from '../validators.js';
+import { applyOperation } from './handlers/index.js';
+import { preprocessOperations } from './preprocessor.js';
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Apply a sequence of edit operations to a DOCX file and return the modified DOCX as a Buffer.
+ */
+export async function editDocxWithOperations(docxPath, operations, options = {}) {
+    return withErrorContext(async () => {
+        validateDocxPath(docxPath);
+        validateOperations(operations);
+        const normalizedPath = docxPath.trim();
+        const baseDir = options.baseDir ?? path.dirname(normalizedPath);
+        const parseOptions = {
+            includeImages: options.includeImages ?? DEFAULT_CONVERSION_OPTIONS.includeImages,
+            preserveFormatting: options.preserveFormatting ?? DEFAULT_CONVERSION_OPTIONS.preserveFormatting,
+            ...(options.styleMap && { styleMap: options.styleMap }),
+        };
+        // Read DOCX → HTML
+        const docxResult = await parseDocxToHtml(normalizedPath, parseOptions);
+        let html = docxResult.html;
+        const { documentDefaults } = docxResult;
+        // Preprocess operations (e.g., convert local image paths to base64)
+        const preprocessedOps = await preprocessOperations(operations, baseDir);
+        // Apply each operation sequentially
+        for (let i = 0; i < preprocessedOps.length; i++) {
+            const op = preprocessedOps[i];
+            try {
+                const validatedOp = DocxOperationSchema.parse(op);
+                html = applyOperation(html, validatedOp, baseDir);
+            }
+            catch (error) {
+                if (error instanceof DocxError)
+                    throw error;
+                // Zod validation errors
+                if (error instanceof Error && 'issues' in error) {
+                    throw new DocxError(`Invalid operation at index ${i}: ${error.message}`, DocxErrorCode.OPERATION_FAILED, { path: normalizedPath, operationIndex: i, operation: op, validationError: error });
+                }
+                // Other errors
+                throw new DocxError(`Failed to apply operation at index ${i}: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED, { path: normalizedPath, operationIndex: i, operation: op });
+            }
+        }
+        // HTML → DOCX, preserving the original document's default styles
+        return await createDocxFromHtml(html, { baseDir, documentDefaults });
+    }, DocxErrorCode.DOCX_EDIT_FAILED, { path: docxPath, operationCount: operations.length });
+}

package/dist/tools/docx/operations/operation-handlers.d.ts

@@ -0,0 +1,3 @@
+import type { DocxStructure } from '../types.js';
+import type { DocxOperation } from '../types.js';
+export declare function applyOperationToStructure(structure: DocxStructure, op: DocxOperation, baseDir: string): Promise<void>;

package/dist/tools/docx/operations/operation-handlers.js

@@ -0,0 +1,67 @@
+import { DocxError, DocxErrorCode } from '../errors.js';
+import { createDocxFromMarkdown } from '../builders/markdown-builder.js';
+import { parseDocxStructure } from '../structure.js';
+import { buildMarkdownTableFromRows, prepareImageForDocx, createImageRun, } from '../utils.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+// @ts-ignore
+import * as docx from 'docx';
+const { Paragraph, AlignmentType } = docx;
+export async function applyOperationToStructure(structure, op, baseDir) {
+    switch (op.type) {
+        case 'replaceText':
+            throw new DocxError('replaceText should use XML manipulation', DocxErrorCode.UNSUPPORTED_OPERATION);
+        case 'appendMarkdown':
+            await handleAppendMarkdown(structure, op, baseDir);
+            break;
+        case 'insertTable':
+            await handleInsertTable(structure, op);
+            break;
+        case 'insertImage':
+            await handleInsertImage(structure, op, baseDir);
+            break;
+        default:
+            throw new DocxError(`Unknown operation: ${op.type}`, DocxErrorCode.UNKNOWN_OPERATION);
+    }
+}
+async function handleAppendMarkdown(structure, op, baseDir) {
+    if (!op.markdown?.trim())
+        return;
+    const appendBuffer = await createDocxFromMarkdown(op.markdown, { baseDir });
+    const appendStructure = await parseDocxStructure(appendBuffer);
+    structure.elements.push(...appendStructure.elements);
+    for (const [relId, imgBuffer] of appendStructure.images.entries()) {
+        structure.images.set(relId, imgBuffer);
+    }
+    for (const [relId, rel] of appendStructure.relationships.entries()) {
+        structure.relationships.set(relId, rel);
+    }
+}
+async function handleInsertTable(structure, op) {
+    let tableMarkdown = op.markdownTable;
+    if (!tableMarkdown && op.rows?.length) {
+        tableMarkdown = buildMarkdownTableFromRows(op.rows);
+    }
+    if (!tableMarkdown?.trim())
+        return;
+    const tableBuffer = await createDocxFromMarkdown(tableMarkdown, {});
+    const tableStructure = await parseDocxStructure(tableBuffer);
+    const tableElement = tableStructure.elements.find(el => el.type === 'table');
+    if (tableElement) {
+        structure.elements.push(tableElement);
+    }
+    else {
+        structure.elements.push(...tableStructure.elements);
+    }
+}
+async function handleInsertImage(structure, op, baseDir) {
+    if (!op.imagePath?.trim())
+        return;
+    const imageData = await prepareImageForDocx(op.imagePath, op.altText || '', baseDir);
+    const imageRun = createImageRun(imageData);
+    const paragraph = new Paragraph({
+        children: [imageRun],
+        alignment: AlignmentType.CENTER,
+    });
+    structure.elements.push({ type: 'paragraph', content: paragraph });
+}