@wonderwhy-er/desktop-commander 0.2.34 → 0.2.35

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

@@ -0,0 +1,14 @@
+/**
+ * DOCX Operation Preprocessor
+ *
+ * Preprocesses operations before execution (e.g., converting local image paths to base64).
+ * Follows Single Responsibility Principle — only handles operation preprocessing.
+ *
+ * @module docx/operations/preprocessor
+ */
+import type { DocxOperation } from '../types.js';
+/**
+ * Resolve local image paths to base64 data URLs before operations are applied.
+ * html-to-docx cannot handle `file://` URLs — only base64 data URLs and HTTP URLs work.
+ */
+export declare function preprocessOperations(operations: DocxOperation[], baseDir: string): Promise<DocxOperation[]>;

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

@@ -0,0 +1,44 @@
+/**
+ * DOCX Operation Preprocessor
+ *
+ * Preprocesses operations before execution (e.g., converting local image paths to base64).
+ * Follows Single Responsibility Principle — only handles operation preprocessing.
+ *
+ * @module docx/operations/preprocessor
+ */
+import fs from 'fs/promises';
+import { DocxError, DocxErrorCode } from '../errors.js';
+import { isDataUrl, isUrl, resolveImagePath } from '../utils/paths.js';
+import { getMimeType } from '../utils/images.js';
+/**
+ * Resolve local image paths to base64 data URLs before operations are applied.
+ * html-to-docx cannot handle `file://` URLs — only base64 data URLs and HTTP URLs work.
+ */
+export async function preprocessOperations(operations, baseDir) {
+    const processed = [];
+    for (const op of operations) {
+        if (op.type !== 'insertImage') {
+            processed.push(op);
+            continue;
+        }
+        const imgOp = op;
+        const trimmedPath = imgOp.imagePath?.trim();
+        if (!trimmedPath || isDataUrl(trimmedPath) || isUrl(trimmedPath)) {
+            processed.push(op);
+            continue;
+        }
+        const resolvedPath = resolveImagePath(trimmedPath, baseDir);
+        try {
+            const imageBuffer = await fs.readFile(resolvedPath);
+            const mimeType = getMimeType(resolvedPath) || 'image/png';
+            processed.push({
+                ...imgOp,
+                imagePath: `data:${mimeType};base64,${imageBuffer.toString('base64')}`,
+            });
+        }
+        catch (err) {
+            throw new DocxError(`Failed to read image file: ${trimmedPath} (resolved: ${resolvedPath}). ${err instanceof Error ? err.message : String(err)}`, DocxErrorCode.INVALID_IMAGE_FILE, { imagePath: trimmedPath, resolvedPath, baseDir });
+        }
+    }
+    return processed;
+}

package/dist/tools/docx/operations/xml-replacer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * XML Text Replacer
+ * Handles direct XML manipulation for text replacements (preserves formatting)
+ */
+/**
+ * Replace text directly in DOCX XML without converting to markdown
+ * This preserves all formatting, tables, styles, etc.
+ */
+export declare function replaceTextInDocxXml(docxPath: string, searchText: string, replaceText: string): Promise<Buffer>;

package/dist/tools/docx/operations/xml-replacer.js

@@ -0,0 +1,35 @@
+/**
+ * XML Text Replacer
+ * Handles direct XML manipulation for text replacements (preserves formatting)
+ */
+import fs from 'fs/promises';
+import JSZip from 'jszip';
+import { DocxError, DocxErrorCode, withErrorContext } from '../errors.js';
+/**
+ * Replace text directly in DOCX XML without converting to markdown
+ * This preserves all formatting, tables, styles, etc.
+ */
+export async function replaceTextInDocxXml(docxPath, searchText, replaceText) {
+    return withErrorContext(async () => {
+        const docxBuffer = await fs.readFile(docxPath);
+        const zip = await JSZip.loadAsync(docxBuffer);
+        const documentXml = await zip.file('word/document.xml')?.async('string');
+        if (!documentXml) {
+            throw new DocxError('Invalid DOCX file: word/document.xml not found', DocxErrorCode.INVALID_DOCX, { path: docxPath });
+        }
+        // Escape XML special characters
+        const escapeXml = (str) => str
+            .replace(/&/g, '&')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+        const escapedSearch = escapeXml(searchText);
+        const escapedReplace = escapeXml(replaceText);
+        // Simple replacement in text nodes
+        const modifiedXml = documentXml.replace(new RegExp(escapedSearch, 'g'), escapedReplace);
+        zip.file('word/document.xml', modifiedXml);
+        const arrayBuffer = await zip.generateAsync({ type: 'uint8array' });
+        return Buffer.from(arrayBuffer);
+    }, DocxErrorCode.DOCX_XML_REPLACE_FAILED, { searchText, replaceText });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * DOCX Creation and Editing Operations
+ *
+ * Main entry point for DOCX operations. This module provides:
+ * - Creating DOCX files from markdown
+ * - Editing existing DOCX files via operations
+ *
+ * @module docx/operations
+ */
+import { createDocxFromMarkdown } from './builders/markdown-builder.js';
+import { editDocxWithOperations } from './operations/index.js';
+export type { DocxBuildOptions, DocxEditOptions, DocxOperation, DocxReplaceTextOperation, DocxAppendMarkdownOperation, DocxInsertTableOperation, DocxInsertImageOperation, } from './types.js';
+export { createDocxFromMarkdown, editDocxWithOperations };

package/dist/tools/docx/operations.js

@@ -0,0 +1,13 @@
+/**
+ * DOCX Creation and Editing Operations
+ *
+ * Main entry point for DOCX operations. This module provides:
+ * - Creating DOCX files from markdown
+ * - Editing existing DOCX files via operations
+ *
+ * @module docx/operations
+ */
+import { createDocxFromMarkdown } from './builders/markdown-builder.js';
+import { editDocxWithOperations } from './operations/index.js';
+// Re-export main functions
+export { createDocxFromMarkdown, editDocxWithOperations };

package/dist/tools/docx/parsers/image-extractor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Image Extractor
+ * Utilities for extracting and handling images from DOCX files
+ */
+import type { ZipArchive } from './zip-reader.js';
+import type { DocxRelationship } from '../types.js';
+/**
+ * Get MIME type from file extension or target path
+ */
+export declare function getMimeTypeForTarget(target: string): string;
+/**
+ * Extract all images from a DOCX ZIP archive
+ */
+export declare function extractImagesFromZip(zip: ZipArchive, relMap: Map<string, DocxRelationship>): Map<string, Buffer>;
+/**
+ * Resolve image relationship ID from drawing or pict element
+ */
+export declare function resolveImageRelId(element: Element): string | null;

package/dist/tools/docx/parsers/image-extractor.js

@@ -0,0 +1,61 @@
+/**
+ * Image Extractor
+ * Utilities for extracting and handling images from DOCX files
+ */
+import path from 'path';
+import { readZipFileBuffer } from './zip-reader.js';
+/**
+ * Get MIME type from file extension or target path
+ */
+export function getMimeTypeForTarget(target) {
+    const ext = path.extname(target).toLowerCase();
+    const mimeTypes = {
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.bmp': 'image/bmp',
+        '.webp': 'image/webp',
+        '.svg': 'image/svg+xml',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+}
+/**
+ * Extract all images from a DOCX ZIP archive
+ */
+export function extractImagesFromZip(zip, relMap) {
+    const images = new Map();
+    for (const [relId, rel] of relMap.entries()) {
+        if (!rel.type.includes('/image'))
+            continue;
+        const targetPath = rel.target.startsWith('word/')
+            ? rel.target
+            : `word/${rel.target.replace(/^\/?/, '')}`;
+        const imgBuffer = readZipFileBuffer(zip, targetPath);
+        if (imgBuffer) {
+            images.set(relId, imgBuffer);
+        }
+    }
+    return images;
+}
+/**
+ * Resolve image relationship ID from drawing or pict element
+ */
+export function resolveImageRelId(element) {
+    // Try drawing element first (newer format)
+    const blips = element.getElementsByTagName('a:blip');
+    for (let i = 0; i < blips.length; i++) {
+        const blip = blips[i];
+        const relId = blip.getAttribute('r:embed') || blip.getAttribute('embed');
+        if (relId)
+            return relId;
+    }
+    // Try pict element (older format)
+    const imagedata = element.getElementsByTagName('v:imagedata');
+    for (let i = 0; i < imagedata.length; i++) {
+        const relId = imagedata[i].getAttribute('r:id') || imagedata[i].getAttribute('id');
+        if (relId)
+            return relId;
+    }
+    return null;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * DOCX Parsers
+ * Centralized exports for all parsing utilities
+ */
+export * from './zip-reader.js';
+export * from './xml-parser.js';
+export * from './image-extractor.js';
+export * from './paragraph-parser.js';
+export * from './table-parser.js';

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

@@ -0,0 +1,9 @@
+/**
+ * DOCX Parsers
+ * Centralized exports for all parsing utilities
+ */
+export * from './zip-reader.js';
+export * from './xml-parser.js';
+export * from './image-extractor.js';
+export * from './paragraph-parser.js';
+export * from './table-parser.js';

package/dist/tools/docx/parsers/paragraph-parser.d.ts

@@ -0,0 +1,2 @@
+import type { DocxParagraph } from '../types.js';
+export declare function parseParagraphElement(paragraph: Element, images: Map<string, Buffer>, headingLevel: number | null): DocxParagraph | null;

package/dist/tools/docx/parsers/paragraph-parser.js

@@ -0,0 +1,88 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+// @ts-ignore
+import * as docx from 'docx';
+const { Paragraph, TextRun, ImageRun, HeadingLevel } = docx;
+import { getElementChildren } from './xml-parser.js';
+import { resolveImageRelId } from './image-extractor.js';
+export function parseParagraphElement(paragraph, images, headingLevel) {
+    const runs = extractRunsFromParagraph(paragraph, images);
+    if (runs.length === 0) {
+        return null;
+    }
+    return new Paragraph({
+        children: runs,
+        heading: headingLevel ? getDocxHeadingLevel(headingLevel) : undefined,
+    });
+}
+function extractRunsFromParagraph(paragraph, images) {
+    const runs = [];
+    const children = getElementChildren(paragraph);
+    for (const child of children) {
+        const nodeName = child.nodeName;
+        if (nodeName === 'w:r') {
+            const textRuns = extractTextRun(child, images);
+            runs.push(...textRuns);
+        }
+        else if (nodeName === 'w:hyperlink') {
+            const linkRuns = child.getElementsByTagName('w:r');
+            for (let i = 0; i < linkRuns.length; i++) {
+                const textRuns = extractTextRun(linkRuns[i], images);
+                runs.push(...textRuns);
+            }
+        }
+    }
+    return runs;
+}
+function extractTextRun(run, images) {
+    const runs = [];
+    const rPr = run.getElementsByTagName('w:rPr')[0];
+    const isBold = rPr?.getElementsByTagName('w:b').length > 0;
+    const isItalic = rPr?.getElementsByTagName('w:i').length > 0;
+    const children = getElementChildren(run);
+    for (const child of children) {
+        const nodeName = child.nodeName;
+        if (nodeName === 'w:t') {
+            const text = child.textContent || '';
+            if (text) {
+                runs.push(new TextRun({
+                    text,
+                    bold: isBold,
+                    italics: isItalic,
+                }));
+            }
+        }
+        else if (nodeName === 'w:tab') {
+            runs.push(new TextRun({ text: '\t' }));
+        }
+        else if (nodeName === 'w:br') {
+            runs.push(new TextRun({ text: '\n', break: 1 }));
+        }
+        else if (nodeName === 'w:drawing' || nodeName === 'w:pict') {
+            const relId = resolveImageRelId(child);
+            if (relId && images.has(relId)) {
+                try {
+                    runs.push(new ImageRun({
+                        data: images.get(relId),
+                        transformation: { width: 600, height: 400 },
+                    }));
+                }
+                catch (err) {
+                    // Skip invalid images
+                }
+            }
+        }
+    }
+    return runs;
+}
+function getDocxHeadingLevel(level) {
+    const levelMap = {
+        1: HeadingLevel.HEADING_1,
+        2: HeadingLevel.HEADING_2,
+        3: HeadingLevel.HEADING_3,
+        4: HeadingLevel.HEADING_4,
+        5: HeadingLevel.HEADING_5,
+        6: HeadingLevel.HEADING_6,
+    };
+    return levelMap[level] ?? HeadingLevel.HEADING_1;
+}

package/dist/tools/docx/parsers/table-parser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Table Parser
+ * Parses DOCX table elements to DOCX library Table objects
+ */
+import type { DocxTable } from '../types.js';
+/**
+ * Parse a table element to DOCX Table
+ */
+export declare function parseTableElement(table: Element, images: Map<string, Buffer>): DocxTable | null;

package/dist/tools/docx/parsers/table-parser.js

@@ -0,0 +1,72 @@
+/**
+ * Table Parser
+ * Parses DOCX table elements to DOCX library Table objects
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+// @ts-ignore
+import * as docx from 'docx';
+const { Table, TableRow, TableCell, Paragraph, WidthType } = docx;
+import { parseParagraphElement } from './paragraph-parser.js';
+/**
+ * Parse a table element to DOCX Table
+ */
+export function parseTableElement(table, images) {
+    const rows = [];
+    const rowNodes = table.getElementsByTagName('w:tr');
+    for (let i = 0; i < rowNodes.length; i++) {
+        const rowNode = rowNodes[i];
+        const row = parseTableRow(rowNode, images);
+        if (row) {
+            rows.push(row);
+        }
+    }
+    if (rows.length === 0) {
+        return null;
+    }
+    return new Table({
+        width: { size: 100, type: WidthType.PERCENTAGE },
+        rows,
+    });
+}
+/**
+ * Parse a table row element
+ */
+function parseTableRow(rowNode, images) {
+    const cells = [];
+    const cellNodes = rowNode.getElementsByTagName('w:tc');
+    for (let j = 0; j < cellNodes.length; j++) {
+        const cellNode = cellNodes[j];
+        const cell = parseTableCell(cellNode, images);
+        if (cell) {
+            cells.push(cell);
+        }
+    }
+    if (cells.length === 0) {
+        return null;
+    }
+    return new TableRow({
+        children: cells,
+    });
+}
+/**
+ * Parse a table cell element
+ */
+function parseTableCell(cellNode, images) {
+    const cellParagraphs = [];
+    const paragraphNodes = cellNode.getElementsByTagName('w:p');
+    for (let k = 0; k < paragraphNodes.length; k++) {
+        const paraNode = paragraphNodes[k];
+        const para = parseParagraphElement(paraNode, images, null);
+        if (para) {
+            cellParagraphs.push(para);
+        }
+    }
+    // Ensure at least one paragraph per cell
+    if (cellParagraphs.length === 0) {
+        cellParagraphs.push(new Paragraph({ text: '' }));
+    }
+    return new TableCell({
+        children: cellParagraphs,
+    });
+}

package/dist/tools/docx/parsers/xml-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * XML Parser Utilities
+ * Helper functions for parsing DOCX XML content
+ */
+import type { DocxRelationship } from '../types.js';
+/**
+ * Get all element children of a node
+ */
+export declare function getElementChildren(node: Node): Element[];
+/**
+ * Get attribute value, checking both direct and namespaced attributes
+ */
+export declare function getAttributeValue(node: Element, name: string): string | null;
+/**
+ * Parse XML string to Document
+ */
+export declare function parseXml(xml: string): Document;
+/**
+ * Extract relationship map from relationships XML
+ */
+export declare function extractRelationshipMap(relsXml: string | null): Map<string, DocxRelationship>;
+/**
+ * Get heading level from paragraph element
+ */
+export declare function getHeadingLevelFromParagraph(paragraph: Element): number | null;

package/dist/tools/docx/parsers/xml-parser.js

@@ -0,0 +1,71 @@
+/**
+ * XML Parser Utilities
+ * Helper functions for parsing DOCX XML content
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Get all element children of a node
+ */
+export function getElementChildren(node) {
+    const children = [];
+    for (let i = 0; i < node.childNodes.length; i++) {
+        const child = node.childNodes[i];
+        if (child.nodeType === 1) { // ELEMENT_NODE
+            children.push(child);
+        }
+    }
+    return children;
+}
+/**
+ * Get attribute value, checking both direct and namespaced attributes
+ */
+export function getAttributeValue(node, name) {
+    return node.getAttribute(name) || node.getAttribute(`w:${name}`) || null;
+}
+/**
+ * Parse XML string to Document
+ */
+export function parseXml(xml) {
+    const parser = new DOMParser();
+    return parser.parseFromString(xml, 'application/xml');
+}
+/**
+ * Extract relationship map from relationships XML
+ */
+export function extractRelationshipMap(relsXml) {
+    const relMap = new Map();
+    if (!relsXml)
+        return relMap;
+    const relDoc = parseXml(relsXml);
+    const rels = relDoc.getElementsByTagName('Relationship');
+    for (let i = 0; i < rels.length; i++) {
+        const rel = rels[i];
+        const id = rel.getAttribute('Id');
+        const type = rel.getAttribute('Type') || '';
+        const target = rel.getAttribute('Target') || '';
+        if (id && target) {
+            relMap.set(id, { target, type });
+        }
+    }
+    return relMap;
+}
+/**
+ * Get heading level from paragraph element
+ */
+export function getHeadingLevelFromParagraph(paragraph) {
+    const pPr = paragraph.getElementsByTagName('w:pPr')[0];
+    if (!pPr)
+        return null;
+    const pStyle = pPr.getElementsByTagName('w:pStyle')[0];
+    if (!pStyle)
+        return null;
+    const styleVal = getAttributeValue(pStyle, 'val');
+    if (!styleVal)
+        return null;
+    const match = styleVal.match(/heading\s*([1-6])/i);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}

package/dist/tools/docx/parsers/zip-reader.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ZIP File Reader
+ * Utilities for reading files from DOCX ZIP archives
+ */
+declare const PizZip: any;
+export type ZipArchive = InstanceType<typeof PizZip>;
+/**
+ * Create a ZIP archive from a buffer
+ */
+export declare function createZipFromBuffer(buffer: Buffer): ZipArchive;
+/**
+ * Read a text file from a ZIP archive
+ */
+export declare function readZipFileText(zip: ZipArchive, filePath: string): string | null;
+/**
+ * Read a binary file from a ZIP archive as Buffer
+ */
+export declare function readZipFileBuffer(zip: ZipArchive, filePath: string): Buffer | null;
+/**
+ * Check if a file exists in the ZIP archive
+ */
+export declare function zipFileExists(zip: ZipArchive, filePath: string): boolean;
+export {};

package/dist/tools/docx/parsers/zip-reader.js

@@ -0,0 +1,52 @@
+/**
+ * ZIP File Reader
+ * Utilities for reading files from DOCX ZIP archives
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const PizZip = require('pizzip');
+/**
+ * Create a ZIP archive from a buffer
+ */
+export function createZipFromBuffer(buffer) {
+    return new PizZip(buffer);
+}
+/**
+ * Read a text file from a ZIP archive
+ */
+export function readZipFileText(zip, filePath) {
+    const file = zip.file(filePath);
+    if (!file)
+        return null;
+    if (typeof file.asText === 'function') {
+        return file.asText();
+    }
+    if (typeof file.asBinary === 'function') {
+        return Buffer.from(file.asBinary(), 'binary').toString('utf8');
+    }
+    return null;
+}
+/**
+ * Read a binary file from a ZIP archive as Buffer
+ */
+export function readZipFileBuffer(zip, filePath) {
+    const file = zip.file(filePath);
+    if (!file)
+        return null;
+    if (typeof file.asUint8Array === 'function') {
+        return Buffer.from(file.asUint8Array());
+    }
+    if (typeof file.asNodeBuffer === 'function') {
+        return file.asNodeBuffer();
+    }
+    if (typeof file.asBinary === 'function') {
+        return Buffer.from(file.asBinary(), 'binary');
+    }
+    return null;
+}
+/**
+ * Check if a file exists in the ZIP archive
+ */
+export function zipFileExists(zip, filePath) {
+    return zip.file(filePath) !== null;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * DOCX Structure Parser and Builder
+ *
+ * Provides structure-preserving parsing and building of DOCX files.
+ * This approach maintains tables, images, and formatting at the DOCX element level,
+ * avoiding lossy markdown round-trips.
+ */
+import type { DocxStructure, DocxElement } from './types.js';
+export type { DocxElement, DocxStructure };
+/**
+ * Parse a DOCX file into structured elements that can be manipulated and rebuilt
+ *
+ * @param buffer - DOCX file buffer
+ * @returns Structured representation of the DOCX document
+ * @throws {DocxError} If the DOCX file is invalid or cannot be parsed
+ */
+export declare function parseDocxStructure(buffer: Buffer): Promise<DocxStructure>;
+/**
+ * Build a DOCX file from structured elements
+ *
+ * @param structure - Structured DOCX representation
+ * @returns Buffer containing the DOCX file
+ * @throws {DocxError} If document building fails
+ */
+export declare function buildDocxFromStructure(structure: DocxStructure): Promise<Buffer>;