@wonderwhy-er/desktop-commander 0.2.35 → 0.2.37

package/dist/tools/docx/dom.js

@@ -0,0 +1,448 @@
+/**
+ * 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;
+}
+/**
+ * Return ALL top‑level tables that are logically in the body, including those
+ * wrapped in structured document tags (w:sdt / w:sdtContent).
+ *
+ * Previous logic only saw tables that were direct children of <w:body>. That
+ * meant tables inside SDTs were invisible to table operations and readDocxOutline.
+ * This helper walks the body tree and collects any <w:tbl> that appears as a
+ * *first‑class* block (we do not recurse into tables themselves, so nested
+ * tables are not double‑counted).
+ */
+export function getAllBodyTables(body) {
+    const result = [];
+    function collectFromNode(node) {
+        const name = node.nodeName;
+        if (name === 'w:tbl') {
+            result.push(node);
+            return; // don't recurse into tables to avoid nested counting
+        }
+        // If this is a structured document tag, look into its content container.
+        if (name === 'w:sdt') {
+            const sdtContent = findDirectChild(node, 'w:sdtContent');
+            if (sdtContent) {
+                for (const child of nodeListToArray(sdtContent.childNodes)) {
+                    if (child.nodeType === 1)
+                        collectFromNode(child);
+                }
+            }
+            return;
+        }
+        // Generic container: recurse into element children.
+        for (const child of nodeListToArray(node.childNodes)) {
+            if (child.nodeType === 1)
+                collectFromNode(child);
+        }
+    }
+    for (const child of getBodyChildren(body)) {
+        collectFromNode(child);
+    }
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// 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;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Table content extraction
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Extract all text content from a table cell (w:tc).
+ * Returns the concatenated text from all paragraphs in the cell.
+ */
+export function getCellText(tc) {
+    const paragraphs = tc.getElementsByTagName('w:p');
+    const texts = [];
+    for (let i = 0; i < paragraphs.length; i++) {
+        const p = paragraphs.item(i);
+        if (p) {
+            const text = getParagraphText(p).trim();
+            if (text)
+                texts.push(text);
+        }
+    }
+    return texts.join(' '); // Join multiple paragraphs in cell with space
+}
+/**
+ * Extract all rows from a table (w:tbl).
+ * Returns an array of rows, where each row is an array of cell text strings.
+ * First row is treated as header if it exists.
+ */
+export function getTableContent(tbl) {
+    const rows = [];
+    for (const child of nodeListToArray(tbl.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:tr') {
+            rows.push(child);
+        }
+    }
+    if (rows.length === 0) {
+        return { rows: [] };
+    }
+    // Extract cells from each row
+    const tableRows = [];
+    for (const row of rows) {
+        const cells = [];
+        for (const child of nodeListToArray(row.childNodes)) {
+            if (child.nodeType === 1 && child.nodeName === 'w:tc') {
+                cells.push(getCellText(child));
+            }
+        }
+        if (cells.length > 0) {
+            tableRows.push(cells);
+        }
+    }
+    // First row might be header - check if it has bold formatting
+    // For simplicity, we'll treat first row as potential header
+    // User can determine this based on style or content
+    if (tableRows.length > 0) {
+        const firstRow = tableRows[0];
+        const restRows = tableRows.slice(1);
+        return {
+            headers: firstRow.length > 0 ? firstRow : undefined,
+            rows: restRows.length > 0 ? restRows : [],
+        };
+    }
+    return { rows: tableRows };
+}
+/**
+ * Get table style from w:tblPr/w:tblStyle/@w:val, or null if absent.
+ */
+export function getTableStyle(tbl) {
+    const tblPr = tbl.getElementsByTagName('w:tblPr').item(0);
+    if (!tblPr)
+        return null;
+    const tblStyle = tblPr.getElementsByTagName('w:tblStyle').item(0);
+    if (!tblStyle)
+        return null;
+    return tblStyle.getAttribute('w:val');
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Image reference extraction
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Extract image reference from a w:drawing element.
+ * Returns the relationship ID (rId) and media file path if found.
+ */
+export function getImageReference(drawing) {
+    // Find a:blip/@r:embed to get the relationship ID
+    const blip = drawing.getElementsByTagName('a:blip').item(0);
+    if (!blip)
+        return { rId: null, mediaPath: null };
+    const rId = blip.getAttribute('r:embed');
+    if (!rId)
+        return { rId: null, mediaPath: null };
+    // Media path will be resolved from relationships file
+    // For now, return the rId - the caller will resolve it from rels
+    return { rId, mediaPath: 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 remove/recreate runs or remove paragraph properties.
+ *
+ * WARNING: This function does NOT preserve multiple runs with different styles.
+ * Use setParagraphTextPreservingStyles() for cells with multiple styled runs.
+ */
+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 = '';
+    }
+}
+/**
+ * Replace paragraph text while preserving all run styles.
+ *
+ * This function preserves the structure of all runs (w:r) and their
+ * properties (w:rPr), distributing the new text across existing runs.
+ *
+ * Strategy:
+ * 1. Collect all runs with their properties
+ * 2. Distribute new text across runs (preserving run count and styles)
+ * 3. If new text is longer, extend the last run
+ * 4. If new text is shorter, clear excess runs but keep their structure
+ */
+export function setParagraphTextPreservingStyles(p, text) {
+    const doc = p.ownerDocument;
+    if (!doc)
+        return;
+    // Work on ALL <w:t> descendants, not just direct children.
+    // This covers runs inside hyperlinks, smart tags, etc.
+    const tNodes = p.getElementsByTagName('w:t');
+    if (tNodes.length === 0) {
+        // No text nodes exist - create a minimal run + text.
+        const r = doc.createElement('w:r');
+        const t = doc.createElement('w:t');
+        t.setAttribute('xml:space', 'preserve');
+        t.textContent = text;
+        r.appendChild(t);
+        p.appendChild(r);
+        return;
+    }
+    // First text node gets the NEW text.
+    const first = tNodes.item(0);
+    first.textContent = text;
+    first.setAttribute('xml:space', 'preserve');
+    // All other text nodes are cleared, but their runs (and w:rPr) remain,
+    // so formatting structures are preserved while old text disappears.
+    for (let i = 1; i < tNodes.length; i++) {
+        const t = tNodes.item(i);
+        if (t)
+            t.textContent = '';
+    }
+}
+/**
+ * Replace cell text while preserving ALL paragraphs and their styles.
+ *
+ * This function works at the cell level:
+ * - Preserves ALL paragraphs in the cell (doesn't remove any)
+ * - Updates text in the first paragraph while preserving its styles
+ * - Keeps all other paragraphs intact with their original text and styles
+ *
+ * This ensures that cells with multiple paragraphs (each with different
+ * styles, font sizes, etc.) maintain their structure after text replacement.
+ *
+ * Example: If a cell has:
+ *   - Paragraph 1: "LAWN AND LANDSCAPE" (Heading1 style, large font, red color)
+ *   - Paragraph 2: "Take your weekends back..." (Normal style, smaller font, black color)
+ *
+ * Replacing with "EARTH AND MOUNTAIN" will:
+ *   - Update paragraph 1 to "EARTH AND MOUNTAIN" (preserving Heading1 style, large font, red color)
+ *   - Keep paragraph 2 completely intact with its original text and style
+ */
+export function setCellTextPreservingStyles(tc, text) {
+    // Convert NodeList to array to avoid live NodeList issues
+    const paragraphs = nodeListToArray(tc.getElementsByTagName('w:p'));
+    if (paragraphs.length === 0) {
+        // Cell has no paragraphs - create one
+        const doc = tc.ownerDocument;
+        if (!doc)
+            return;
+        const p = doc.createElement('w:p');
+        const r = doc.createElement('w:r');
+        const t = doc.createElement('w:t');
+        t.setAttribute('xml:space', 'preserve');
+        t.textContent = text;
+        r.appendChild(t);
+        p.appendChild(r);
+        tc.appendChild(p);
+        return;
+    }
+    // Update first paragraph with new text, preserving all its styles
+    // This function preserves all runs and their properties (colors, bold, italic, etc.)
+    setParagraphTextPreservingStyles(paragraphs[0], text);
+    // CRITICAL: All other paragraphs remain completely untouched
+    // They keep their original text, styles, runs, and all formatting
+    // This ensures multi-paragraph cells maintain their full structure
+}
+// ═══════════════════════════════════════════════════════════════════════
+// 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, DocxTableCellContent, } 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, TableOutline, ImageOutline, 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>;