@wonderwhy-er/desktop-commander 0.2.34 → 0.2.35

package/dist/tools/docx/errors.js

@@ -0,0 +1,48 @@
+/**
+ * DOCX Error Handling
+ *
+ * Centralised error class and async error-wrapping utility.
+ *
+ * @module docx/errors
+ */
+export class DocxError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'DocxError';
+        Error.captureStackTrace?.(this, DocxError);
+    }
+    toJSON() {
+        return { name: this.name, message: this.message, code: this.code, context: this.context };
+    }
+}
+export var DocxErrorCode;
+(function (DocxErrorCode) {
+    DocxErrorCode["INVALID_DOCX"] = "INVALID_DOCX";
+    DocxErrorCode["INVALID_PATH"] = "INVALID_PATH";
+    DocxErrorCode["OPERATION_FAILED"] = "OPERATION_FAILED";
+    DocxErrorCode["UNKNOWN_OPERATION"] = "UNKNOWN_OPERATION";
+    DocxErrorCode["UNSUPPORTED_OPERATION"] = "UNSUPPORTED_OPERATION";
+    DocxErrorCode["DOCX_CREATE_FAILED"] = "DOCX_CREATE_FAILED";
+    DocxErrorCode["DOCX_EDIT_FAILED"] = "DOCX_EDIT_FAILED";
+    DocxErrorCode["DOCX_READ_FAILED"] = "DOCX_READ_FAILED";
+    DocxErrorCode["INVALID_IMAGE_FILE"] = "INVALID_IMAGE_FILE";
+    DocxErrorCode["INVALID_IMAGE_DATA_URL"] = "INVALID_IMAGE_DATA_URL";
+    DocxErrorCode["GET_INFO_FAILED"] = "GET_INFO_FAILED";
+})(DocxErrorCode || (DocxErrorCode = {}));
+/** Wrap an async operation — re-throws existing DocxErrors, wraps everything else. */
+export async function withErrorContext(operation, errorCode, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof DocxError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DocxError(message, errorCode, {
+            ...context,
+            originalError: error instanceof Error ? error.stack : String(error),
+        });
+    }
+}

package/dist/tools/docx/extractors/images.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Image Extractor (Mammoth Fallback)
+ *
+ * Extracts images from HTML generated by mammoth.js fallback.
+ * Only used when styled parser is not available.
+ *
+ * @module docx/extractors/images
+ */
+import type { DocxImage } from '../types.js';
+/**
+ * Extract base64-encoded images from HTML (mammoth.js fallback only).
+ * Returns empty array if parsing fails.
+ */
+export declare function extractImagesFromHtml(html: string): DocxImage[];

package/dist/tools/docx/extractors/images.js

@@ -0,0 +1,40 @@
+/**
+ * DOCX Image Extractor (Mammoth Fallback)
+ *
+ * Extracts images from HTML generated by mammoth.js fallback.
+ * Only used when styled parser is not available.
+ *
+ * @module docx/extractors/images
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Extract base64-encoded images from HTML (mammoth.js fallback only).
+ * Returns empty array if parsing fails.
+ */
+export function extractImagesFromHtml(html) {
+    const images = [];
+    try {
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const imgElements = doc.getElementsByTagName('img');
+        for (let i = 0; i < imgElements.length; i++) {
+            const src = imgElements[i].getAttribute('src') || '';
+            const alt = imgElements[i].getAttribute('alt') || '';
+            const match = src.match(/^data:([^;]+);base64,(.+)$/);
+            if (match) {
+                images.push({
+                    id: `img_${i}`,
+                    data: match[2],
+                    mimeType: match[1],
+                    altText: alt || undefined,
+                    originalSize: Buffer.from(match[2], 'base64').length,
+                });
+            }
+        }
+    }
+    catch {
+        // Non-critical
+    }
+    return images;
+}

package/dist/tools/docx/extractors/metadata.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Metadata Extractor
+ *
+ * Extracts document metadata (title, author, dates, etc.) from DOCX core properties.
+ * Follows Single Responsibility Principle — only handles metadata extraction.
+ *
+ * @module docx/extractors/metadata
+ */
+import type { DocxMetadata } from '../types.js';
+/**
+ * Extract metadata from a DOCX buffer.
+ * Returns minimal metadata if extraction fails (non-critical operation).
+ */
+export declare function extractDocxMetadata(buffer: Buffer, fileSize?: number): Promise<DocxMetadata>;

package/dist/tools/docx/extractors/metadata.js

@@ -0,0 +1,64 @@
+/**
+ * DOCX Metadata Extractor
+ *
+ * Extracts document metadata (title, author, dates, etc.) from DOCX core properties.
+ * Follows Single Responsibility Principle — only handles metadata extraction.
+ *
+ * @module docx/extractors/metadata
+ */
+import { createRequire } from 'module';
+import { CORE_PROPERTIES_PATH, DOCX_NAMESPACES } from '../constants.js';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Extract metadata from a DOCX buffer.
+ * Returns minimal metadata if extraction fails (non-critical operation).
+ */
+export async function extractDocxMetadata(buffer, fileSize) {
+    const metadata = { fileSize };
+    try {
+        const JSZip = require('jszip');
+        const zip = await JSZip.loadAsync(buffer);
+        const corePropsFile = zip.file(CORE_PROPERTIES_PATH);
+        if (!corePropsFile)
+            return metadata;
+        const corePropsXml = await corePropsFile.async('string');
+        const doc = new DOMParser().parseFromString(corePropsXml, 'application/xml');
+        /** Extract text content from a namespaced tag. */
+        const getText = (tag, nsList = [DOCX_NAMESPACES.DUBLIN_CORE, DOCX_NAMESPACES.CUSTOM_PROPERTIES]) => {
+            for (const ns of nsList) {
+                const els = doc.getElementsByTagName(`${ns}:${tag}`);
+                if (els.length > 0 && els[0].textContent) {
+                    const text = els[0].textContent.trim();
+                    return text || undefined;
+                }
+            }
+            return undefined;
+        };
+        /** Extract date from a DCTERMS namespaced tag. */
+        const getDate = (tag) => {
+            const els = doc.getElementsByTagName(`${DOCX_NAMESPACES.DCTERMS}:${tag}`);
+            if (els.length > 0 && els[0].textContent) {
+                const dateStr = els[0].textContent.trim();
+                if (dateStr) {
+                    const d = new Date(dateStr);
+                    if (!isNaN(d.getTime()))
+                        return d;
+                }
+            }
+            return undefined;
+        };
+        metadata.title = getText('title');
+        metadata.author = getText('creator');
+        metadata.subject = getText('subject');
+        metadata.description = getText('description');
+        metadata.lastModifiedBy = getText('lastModifiedBy', [DOCX_NAMESPACES.CUSTOM_PROPERTIES]);
+        metadata.revision = getText('revision', [DOCX_NAMESPACES.CUSTOM_PROPERTIES]);
+        metadata.creationDate = getDate('created');
+        metadata.modificationDate = getDate('modified');
+    }
+    catch {
+        // Non-critical — return metadata with fileSize only
+    }
+    return metadata;
+}

package/dist/tools/docx/extractors/sections.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Section Parser
+ *
+ * Parses HTML into structured sections (headings, paragraphs, tables, lists, images).
+ * Follows Single Responsibility Principle — only handles section parsing.
+ *
+ * @module docx/extractors/sections
+ */
+import type { DocxSection } from '../types.js';
+/**
+ * Parse HTML into structured sections.
+ * Returns a single paragraph section if parsing fails.
+ */
+export declare function parseHtmlIntoSections(html: string): DocxSection[];

package/dist/tools/docx/extractors/sections.js

@@ -0,0 +1,61 @@
+/**
+ * DOCX Section Parser
+ *
+ * Parses HTML into structured sections (headings, paragraphs, tables, lists, images).
+ * Follows Single Responsibility Principle — only handles section parsing.
+ *
+ * @module docx/extractors/sections
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Parse HTML into structured sections.
+ * Returns a single paragraph section if parsing fails.
+ */
+export function parseHtmlIntoSections(html) {
+    const sections = [];
+    try {
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const body = doc.getElementsByTagName('body')[0];
+        if (!body) {
+            sections.push({ type: 'paragraph', content: html });
+            return sections;
+        }
+        for (let i = 0; i < body.childNodes.length; i++) {
+            const child = body.childNodes[i];
+            if (child.nodeType !== 1)
+                continue;
+            const element = child;
+            const tag = element.tagName.toLowerCase();
+            const content = element.outerHTML || element.innerHTML;
+            // Heading detection
+            const headingMatch = tag.match(/^h([1-6])$/);
+            if (headingMatch) {
+                sections.push({ type: 'heading', level: parseInt(headingMatch[1], 10), content });
+                continue;
+            }
+            // Other element types
+            switch (tag) {
+                case 'img':
+                    sections.push({ type: 'image', content });
+                    break;
+                case 'table':
+                    sections.push({ type: 'table', content });
+                    break;
+                case 'ul':
+                case 'ol':
+                    sections.push({ type: 'list', content });
+                    break;
+                case 'p':
+                case 'div':
+                    sections.push({ type: 'paragraph', content });
+                    break;
+            }
+        }
+    }
+    catch {
+        sections.push({ type: 'paragraph', content: html });
+    }
+    return sections;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * DOCX → HTML Conversion
+ *
+ * Primary:  Direct DOCX XML parsing (`styled-html-parser`) — preserves inline styles
+ *           (font colours, sizes, families, alignment, highlights, etc.)
+ * Fallback: mammoth.js — semantic-only conversion, strips visual styles.
+ *
+ * @module docx/html
+ */
+import type { DocxParseResult, DocxParseOptions } from './types.js';
+/**
+ * Parse a DOCX file to styled HTML.
+ *
+ * Uses direct XML parsing when `preserveFormatting` is true (default).
+ * Falls back to mammoth.js if direct parsing fails or a custom `styleMap` is provided.
+ */
+export declare function parseDocxToHtml(source: string, options?: DocxParseOptions): Promise<DocxParseResult>;

package/dist/tools/docx/html.js

@@ -0,0 +1,111 @@
+/**
+ * DOCX → HTML Conversion
+ *
+ * Primary:  Direct DOCX XML parsing (`styled-html-parser`) — preserves inline styles
+ *           (font colours, sizes, families, alignment, highlights, etc.)
+ * Fallback: mammoth.js — semantic-only conversion, strips visual styles.
+ *
+ * @module docx/html
+ */
+import fs from 'fs/promises';
+import { createRequire } from 'module';
+import { DocxError, DocxErrorCode, withErrorContext } from './errors.js';
+import { DEFAULT_CONVERSION_OPTIONS } from './constants.js';
+import { isUrl } from './utils/paths.js';
+import { convertDocxToStyledHtml } from './styled-html-parser.js';
+import { extractDocxMetadata } from './extractors/metadata.js';
+import { parseHtmlIntoSections } from './extractors/sections.js';
+import { extractImagesFromHtml } from './extractors/images.js';
+const require = createRequire(import.meta.url);
+const mammoth = require('mammoth');
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Parse a DOCX file to styled HTML.
+ *
+ * Uses direct XML parsing when `preserveFormatting` is true (default).
+ * Falls back to mammoth.js if direct parsing fails or a custom `styleMap` is provided.
+ */
+export async function parseDocxToHtml(source, options = {}) {
+    return withErrorContext(async () => {
+        const { includeImages = DEFAULT_CONVERSION_OPTIONS.includeImages, preserveFormatting = DEFAULT_CONVERSION_OPTIONS.preserveFormatting, styleMap = DEFAULT_CONVERSION_OPTIONS.styleMap, } = options;
+        const buffer = await loadDocxToBuffer(source);
+        let fileSize;
+        if (!isUrl(source)) {
+            try {
+                fileSize = (await fs.stat(source)).size;
+            }
+            catch { /* ignore */ }
+        }
+        const { html: rawHtml, images, documentDefaults } = await convertToHtml(buffer, includeImages, preserveFormatting, styleMap);
+        const metadata = await extractDocxMetadata(buffer, fileSize);
+        const html = postProcessHtml(rawHtml);
+        const sections = parseHtmlIntoSections(html);
+        return { html, metadata, images, sections, documentDefaults };
+    }, DocxErrorCode.DOCX_READ_FAILED, { path: source });
+}
+// ─── Buffer Loading ──────────────────────────────────────────────────────────
+async function loadDocxToBuffer(source) {
+    return withErrorContext(async () => {
+        if (isUrl(source)) {
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new DocxError(`Failed to fetch DOCX from URL: ${response.statusText}`, DocxErrorCode.DOCX_READ_FAILED, { url: source, status: response.status });
+            }
+            return Buffer.from(await response.arrayBuffer());
+        }
+        return await fs.readFile(source);
+    }, DocxErrorCode.DOCX_READ_FAILED, { source });
+}
+// ─── Conversion Dispatch ─────────────────────────────────────────────────────
+/**
+ * Pick the best converter: direct XML parser (preserves styles) or mammoth.js (semantic only).
+ */
+async function convertToHtml(buffer, includeImages, preserveFormatting, styleMap) {
+    // Use the styled XML parser when no custom styleMap is provided and formatting is requested
+    if (preserveFormatting && styleMap.length === 0) {
+        try {
+            return await convertDocxToStyledHtml(buffer, includeImages);
+        }
+        catch {
+            // Fall through to mammoth.js fallback
+        }
+    }
+    const mammothResult = await convertWithMammoth(buffer, includeImages, styleMap, preserveFormatting);
+    return { ...mammothResult, documentDefaults: undefined };
+}
+/** Fallback: mammoth.js (semantic-only — strips visual styles). */
+async function convertWithMammoth(buffer, includeImages, styleMap, preserveFormatting) {
+    const mammothOptions = {};
+    if (includeImages) {
+        mammothOptions.convertImage = mammoth.images.imgElement((image) => image.read('base64').then((base64Data) => ({
+            src: `data:${image.contentType};base64,${base64Data}`,
+        })));
+    }
+    if (styleMap.length > 0) {
+        mammothOptions.styleMap = [...styleMap];
+    }
+    else if (preserveFormatting) {
+        mammothOptions.styleMap = [
+            "p[style-name='Heading 1'] => h1:fresh",
+            "p[style-name='Heading 2'] => h2:fresh",
+            "p[style-name='Heading 3'] => h3:fresh",
+            "p[style-name='Heading 4'] => h4:fresh",
+            "p[style-name='Heading 5'] => h5:fresh",
+            "p[style-name='Heading 6'] => h6:fresh",
+            "p[style-name='Title'] => h1:fresh",
+            "p[style-name='Subtitle'] => h2:fresh",
+            "p[style-name='Quote'] => blockquote:fresh",
+            "r[style-name='Strong'] => strong",
+            "r[style-name='Emphasis'] => em",
+        ];
+    }
+    const result = await mammoth.convertToHtml({ buffer }, mammothOptions);
+    const html = result.value;
+    const images = extractImagesFromHtml(html);
+    return { html, images };
+}
+// ─── Post-Processing ─────────────────────────────────────────────────────────
+/** Minimal whitespace cleanup — preserves all inline style attributes. */
+function postProcessHtml(html) {
+    return html.replace(/>\s{2,}</g, '>\n<').trim();
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+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';

package/dist/tools/docx/index.js

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+// ── 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';

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

@@ -0,0 +1,84 @@
+/**
+ * DOCX to Markdown Conversion
+ * Uses Docxtemplater + XML parsing for reading Word documents
+ */
+/**
+ * DOCX metadata structure
+ */
+export interface DocxMetadata {
+    /** Document title from core properties */
+    title?: string;
+    /** Document author */
+    author?: string;
+    /** Document creator */
+    creator?: string;
+    /** Document subject */
+    subject?: string;
+    /** Document description */
+    description?: string;
+    /** Creation date */
+    creationDate?: Date;
+    /** Last modification date */
+    modificationDate?: Date;
+    /** Last modified by */
+    lastModifiedBy?: string;
+    /** Document revision number */
+    revision?: string;
+    /** File size in bytes */
+    fileSize?: number;
+}
+/**
+ * Embedded image information
+ */
+export interface DocxImage {
+    /** Unique identifier for the image */
+    id: string;
+    /** Base64-encoded image data */
+    data: string;
+    /** MIME type (e.g., "image/png", "image/jpeg") */
+    mimeType: string;
+    /** Alt text if available */
+    altText?: string;
+    /** Original size in bytes */
+    originalSize?: number;
+}
+/**
+ * DOCX section/paragraph structure
+ */
+export interface DocxSection {
+    /** Section type: heading, paragraph, list, table */
+    type: 'heading' | 'paragraph' | 'list' | 'table' | 'image';
+    /** Section content as markdown */
+    content: string;
+    /** Heading level if type is heading */
+    level?: number;
+    /** Associated images if any */
+    images?: DocxImage[];
+}
+/**
+ * Complete DOCX parse result
+ */
+export interface DocxParseResult {
+    /** Document content as markdown */
+    markdown: string;
+    /** Document metadata */
+    metadata: DocxMetadata;
+    /** Extracted images */
+    images: DocxImage[];
+    /** Structured sections (optional, for advanced parsing) */
+    sections?: DocxSection[];
+}
+/**
+ * Convert DOCX to Markdown using Docxtemplater + XML parsing
+ * @param source Path to DOCX file or URL
+ * @param options Conversion options
+ * @returns Parsed DOCX result with markdown and metadata
+ */
+export declare function parseDocxToMarkdown(source: string, options?: {
+    /** Extract images as base64 */
+    includeImages?: boolean;
+    /** Preserve inline formatting (bold, italic) */
+    preserveFormatting?: boolean;
+    /** Custom style mapping */
+    styleMap?: string[];
+}): Promise<DocxParseResult>;