@wonderwhy-er/desktop-commander 0.2.35 → 0.2.36

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

@@ -0,0 +1,8 @@
+/**
+ * Op: set_paragraph_style_at_body_index
+ *
+ * Set (or replace) the paragraph style (w:pPr/w:pStyle) at a given
+ * bodyChildIndex.  Skips if the child is not a w:p.
+ */
+import type { SetParagraphStyleAtBodyIndexOp, OpResult } from '../types.js';
+export declare function applySetParagraphStyleAtBodyIndex(body: Element, op: SetParagraphStyleAtBodyIndexOp): OpResult;

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

@@ -0,0 +1,57 @@
+/**
+ * Op: set_paragraph_style_at_body_index
+ *
+ * Set (or replace) the paragraph style (w:pPr/w:pStyle) at a given
+ * bodyChildIndex.  Skips if the child is not a w:p.
+ */
+import { getBodyChildren, nodeListToArray } from '../dom.js';
+export function applySetParagraphStyleAtBodyIndex(body, op) {
+    const children = getBodyChildren(body);
+    const idx = op.bodyChildIndex;
+    if (idx < 0 || idx >= children.length) {
+        return { op, status: 'skipped', matched: 0, reason: 'index_out_of_range' };
+    }
+    const child = children[idx];
+    if (child.nodeName !== 'w:p') {
+        return { op, status: 'skipped', matched: 0, reason: 'not_a_paragraph' };
+    }
+    const doc = child.ownerDocument;
+    if (!doc)
+        return { op, status: 'skipped', matched: 0, reason: 'no_owner_document' };
+    // Find or create w:pPr
+    let pPr = null;
+    for (const n of nodeListToArray(child.childNodes)) {
+        if (n.nodeType === 1 && n.nodeName === 'w:pPr') {
+            pPr = n;
+            break;
+        }
+    }
+    if (!pPr) {
+        pPr = doc.createElement('w:pPr');
+        if (child.firstChild) {
+            child.insertBefore(pPr, child.firstChild);
+        }
+        else {
+            child.appendChild(pPr);
+        }
+    }
+    // Find or create w:pStyle inside pPr
+    let pStyle = null;
+    for (const n of nodeListToArray(pPr.childNodes)) {
+        if (n.nodeType === 1 && n.nodeName === 'w:pStyle') {
+            pStyle = n;
+            break;
+        }
+    }
+    if (!pStyle) {
+        pStyle = doc.createElement('w:pStyle');
+        if (pPr.firstChild) {
+            pPr.insertBefore(pStyle, pPr.firstChild);
+        }
+        else {
+            pPr.appendChild(pStyle);
+        }
+    }
+    pStyle.setAttribute('w:val', op.style);
+    return { op, status: 'applied', matched: 1 };
+}

package/dist/tools/docx/ops/table-set-cell-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Op: table_set_cell_text
+ *
+ * Set the text content of a specific table cell.
+ * Targets by: tableIndex (0-based among w:tbl in body), row, col.
+ * Applies minimal text replacement inside the cell's first paragraph.
+ */
+import type { TableSetCellTextOp, OpResult } from '../types.js';
+export declare function applyTableSetCellText(body: Element, op: TableSetCellTextOp): OpResult;

package/dist/tools/docx/ops/table-set-cell-text.js

@@ -0,0 +1,72 @@
+/**
+ * Op: table_set_cell_text
+ *
+ * Set the text content of a specific table cell.
+ * Targets by: tableIndex (0-based among w:tbl in body), row, col.
+ * Applies minimal text replacement inside the cell's first paragraph.
+ */
+import { getBodyChildren, nodeListToArray, setParagraphTextMinimal } from '../dom.js';
+export function applyTableSetCellText(body, op) {
+    const children = getBodyChildren(body);
+    // Find the n-th w:tbl
+    let tableCount = 0;
+    let table = null;
+    for (const child of children) {
+        if (child.nodeName === 'w:tbl') {
+            if (tableCount === op.tableIndex) {
+                table = child;
+                break;
+            }
+            tableCount++;
+        }
+    }
+    if (!table) {
+        return { op, status: 'skipped', matched: 0, reason: 'table_not_found' };
+    }
+    // Find the n-th w:tr
+    const rows = [];
+    for (const child of nodeListToArray(table.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:tr') {
+            rows.push(child);
+        }
+    }
+    if (op.row < 0 || op.row >= rows.length) {
+        return { op, status: 'skipped', matched: 0, reason: 'row_out_of_range' };
+    }
+    // Find the n-th w:tc in the row
+    const cells = [];
+    for (const child of nodeListToArray(rows[op.row].childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:tc') {
+            cells.push(child);
+        }
+    }
+    if (op.col < 0 || op.col >= cells.length) {
+        return { op, status: 'skipped', matched: 0, reason: 'col_out_of_range' };
+    }
+    const cell = cells[op.col];
+    // Find first w:p inside the cell and apply minimal text replacement
+    for (const child of nodeListToArray(cell.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:p') {
+            const p = child;
+            const tNodes = p.getElementsByTagName('w:t');
+            if (tNodes.length > 0) {
+                // Existing runs — use minimal replacement
+                setParagraphTextMinimal(p, op.text);
+            }
+            else {
+                // Empty cell — create a run
+                const doc = cell.ownerDocument;
+                if (!doc)
+                    return { op, status: 'skipped', matched: 0, reason: 'no_owner_document' };
+                const r = doc.createElement('w:r');
+                const t = doc.createElement('w:t');
+                t.setAttribute('xml:space', 'preserve');
+                t.textContent = op.text;
+                r.appendChild(t);
+                p.appendChild(r);
+            }
+            return { op, status: 'applied', matched: 1 };
+        }
+    }
+    return { op, status: 'skipped', matched: 0, reason: 'no_paragraph_in_cell' };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * DOCX reading utilities
+ * Extracts text, metadata, and compact outlines from DOCX files.
+ */
+import type { DocxMetadata, DocxParagraph, ReadDocxResult } from './types.js';
+/**
+ * Return a token-efficient outline of a DOCX file.
+ * Every paragraph gets a bodyChildIndex (among ALL w:body children)
+ * plus a paragraphIndex (counting only w:p), style id, and text.
+ */
+export declare function readDocxOutline(filePath: string): Promise<ReadDocxResult>;
+/** Extract plain text from DOCX. */
+export declare function extractTextFromDocx(path: string): Promise<string>;
+/** Get comprehensive metadata. */
+export declare function getDocxMetadata(path: string): Promise<DocxMetadata>;
+/** Extract body XML. */
+export declare function extractBodyXml(path: string): Promise<string>;
+/** Read DOCX file with optional pagination. */
+export declare function readDocx(path: string, options?: {
+    offset?: number;
+    length?: number;
+}): Promise<{
+    text: string;
+    paragraphs: DocxParagraph[];
+    metadata: DocxMetadata;
+    bodyXml: string;
+}>;

package/dist/tools/docx/read.js

@@ -0,0 +1,188 @@
+/**
+ * DOCX reading utilities
+ * Extracts text, metadata, and compact outlines from DOCX files.
+ */
+import fs from 'fs/promises';
+import PizZip from 'pizzip';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { nodeListToArray, getParagraphText, getParagraphStyle, getBody, getBodyChildren, countTables, countImages, } from './dom.js';
+// ═══════════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════════
+async function loadDocx(path) {
+    const inputBuf = await fs.readFile(path);
+    return new PizZip(inputBuf);
+}
+// ═══════════════════════════════════════════════════════════════════════
+// readDocxOutline — compact JSON outline (used by read_docx tool)
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Return a token-efficient outline of a DOCX file.
+ * Every paragraph gets a bodyChildIndex (among ALL w:body children)
+ * plus a paragraphIndex (counting only w:p), style id, and text.
+ */
+export async function readDocxOutline(filePath) {
+    const zip = await loadDocx(filePath);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const xmlStr = docFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const body = getBody(dom);
+    const children = getBodyChildren(body);
+    const paragraphs = [];
+    const stylesSet = new Set();
+    let paragraphIndex = 0;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child.nodeName !== 'w:p')
+            continue;
+        const text = getParagraphText(child).trim();
+        const style = getParagraphStyle(child);
+        if (style)
+            stylesSet.add(style);
+        paragraphs.push({
+            bodyChildIndex: i,
+            paragraphIndex,
+            style,
+            text,
+        });
+        paragraphIndex++;
+    }
+    return {
+        path: filePath,
+        paragraphs,
+        stylesSeen: [...stylesSet].sort(),
+        counts: {
+            tables: countTables(children),
+            images: countImages(body),
+            bodyChildren: children.length,
+        },
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Legacy read functions (used by read_file handler / file handler)
+// ═══════════════════════════════════════════════════════════════════════
+/** Extract plain text from DOCX. */
+export async function extractTextFromDocx(path) {
+    const zip = await loadDocx(path);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const xmlStr = docFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const body = dom.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX: missing w:body');
+    const paragraphs = [];
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1)
+            continue;
+        if (child.nodeName !== 'w:p')
+            continue;
+        const text = getParagraphText(child).trim();
+        if (text)
+            paragraphs.push(text);
+    }
+    return paragraphs.join('\n\n');
+}
+/** Extract paragraphs from DOCX. */
+async function extractParagraphs(path) {
+    const zip = await loadDocx(path);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const xmlStr = docFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const body = dom.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX: missing w:body');
+    const paragraphs = [];
+    let index = 0;
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1)
+            continue;
+        if (child.nodeName !== 'w:p')
+            continue;
+        const text = getParagraphText(child).trim();
+        paragraphs.push({ index, text, hasText: text.length > 0 });
+        index++;
+    }
+    return paragraphs;
+}
+/** Get core properties from DOCX. */
+async function getCoreProperties(zip) {
+    const corePropsFile = zip.file('docProps/core.xml');
+    if (!corePropsFile)
+        return {};
+    const xmlStr = corePropsFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const getProperty = (name) => {
+        const elements = dom.getElementsByTagName(name);
+        if (elements.length > 0)
+            return elements[0].textContent || undefined;
+        return undefined;
+    };
+    return {
+        title: getProperty('dc:title'),
+        author: getProperty('dc:creator'),
+        subject: getProperty('dc:subject'),
+        creator: getProperty('cp:creator'),
+    };
+}
+/** Get comprehensive metadata. */
+export async function getDocxMetadata(path) {
+    const zip = await loadDocx(path);
+    const paragraphs = await extractParagraphs(path);
+    const coreProps = await getCoreProperties(zip);
+    const fullText = paragraphs.map((p) => p.text).join(' ');
+    const wordCount = fullText.split(/\s+/).filter((w) => w.length > 0).length;
+    return { ...coreProps, paragraphCount: paragraphs.length, wordCount };
+}
+/** Extract body XML. */
+export async function extractBodyXml(path) {
+    const inputBuf = await fs.readFile(path);
+    const zip = new PizZip(inputBuf);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const xmlStr = docFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const body = dom.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX: missing w:body');
+    return new XMLSerializer().serializeToString(body);
+}
+/** Read DOCX file with optional pagination. */
+export async function readDocx(path, options) {
+    const zip = await loadDocx(path);
+    const docFile = zip.file('word/document.xml');
+    if (!docFile)
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    const xmlStr = docFile.asText();
+    const dom = new DOMParser().parseFromString(xmlStr, 'application/xml');
+    const body = dom.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX: missing w:body');
+    const allParagraphs = [];
+    let index = 0;
+    for (const child of nodeListToArray(body.childNodes)) {
+        if (child.nodeType !== 1)
+            continue;
+        if (child.nodeName !== 'w:p')
+            continue;
+        const text = getParagraphText(child).trim();
+        allParagraphs.push({ index, text, hasText: text.length > 0 });
+        index++;
+    }
+    let paragraphs = allParagraphs;
+    if (options?.offset !== undefined || options?.length !== undefined) {
+        const offset = options.offset || 0;
+        const length = options.length !== undefined ? options.length : allParagraphs.length;
+        paragraphs = allParagraphs.slice(offset, offset + length);
+    }
+    const metadata = await getDocxMetadata(path);
+    const text = paragraphs.map((p) => p.text).join('\n\n');
+    const bodyXml = new XMLSerializer().serializeToString(body);
+    return { text, paragraphs, metadata, bodyXml };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * DOCX relationship management — Single Responsibility: manage relationships
+ * in word/_rels/document.xml.rels and Content_Types.xml.
+ *
+ * Used for adding images, hyperlinks, and other external resources.
+ */
+import PizZip from 'pizzip';
+/**
+ * Add an image relationship to word/_rels/document.xml.rels and return the rId.
+ *
+ * @param zip The DOCX ZIP archive
+ * @param mediaFileName The filename in word/media/ (e.g., "image1.png")
+ * @returns The relationship ID (e.g., "rId1")
+ */
+export declare function addImageRelationship(zip: PizZip, mediaFileName: string): string;
+/**
+ * Ensure the Content_Types.xml has a Default entry for the given file extension.
+ *
+ * @param zip The DOCX ZIP archive
+ * @param ext The file extension (e.g., ".png")
+ */
+export declare function ensureContentType(zip: PizZip, ext: string): void;

package/dist/tools/docx/relationships.js

@@ -0,0 +1,76 @@
+/**
+ * DOCX relationship management — Single Responsibility: manage relationships
+ * in word/_rels/document.xml.rels and Content_Types.xml.
+ *
+ * Used for adding images, hyperlinks, and other external resources.
+ */
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { nodeListToArray } from './dom.js';
+import { getMimeType } from './constants.js';
+import { DOCX_PATHS, NAMESPACES } from './constants.js';
+/**
+ * Add an image relationship to word/_rels/document.xml.rels and return the rId.
+ *
+ * @param zip The DOCX ZIP archive
+ * @param mediaFileName The filename in word/media/ (e.g., "image1.png")
+ * @returns The relationship ID (e.g., "rId1")
+ */
+export function addImageRelationship(zip, mediaFileName) {
+    const relsPath = DOCX_PATHS.DOCUMENT_RELS;
+    let relsEntry = zip.file(relsPath);
+    // Create .rels file if it doesn't exist
+    if (!relsEntry) {
+        const emptyRels = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+            `<Relationships xmlns="${NAMESPACES.RELS}"></Relationships>`;
+        zip.file(relsPath, emptyRels);
+        relsEntry = zip.file(relsPath);
+    }
+    const relsXml = relsEntry.asText();
+    const relsDom = new DOMParser().parseFromString(relsXml, 'application/xml');
+    const relationships = relsDom.getElementsByTagName('Relationship');
+    // Find max existing rId
+    let maxId = 0;
+    for (const rel of nodeListToArray(relationships)) {
+        const id = rel.getAttribute('Id') || '';
+        const match = id.match(/^rId(\d+)$/);
+        if (match) {
+            maxId = Math.max(maxId, parseInt(match[1], 10));
+        }
+    }
+    const newRId = `rId${maxId + 1}`;
+    // Create new Relationship element
+    const newRel = relsDom.createElement('Relationship');
+    newRel.setAttribute('Id', newRId);
+    newRel.setAttribute('Type', `${NAMESPACES.R}/image`);
+    newRel.setAttribute('Target', `media/${mediaFileName}`);
+    relsDom.documentElement.appendChild(newRel);
+    // Write back
+    const newRelsXml = new XMLSerializer().serializeToString(relsDom);
+    zip.file(relsPath, newRelsXml);
+    return newRId;
+}
+/**
+ * Ensure the Content_Types.xml has a Default entry for the given file extension.
+ *
+ * @param zip The DOCX ZIP archive
+ * @param ext The file extension (e.g., ".png")
+ */
+export function ensureContentType(zip, ext) {
+    const ctPath = DOCX_PATHS.CONTENT_TYPES;
+    const ctEntry = zip.file(ctPath);
+    if (!ctEntry)
+        return;
+    const ctXml = ctEntry.asText();
+    const extNoDot = ext.replace(/^\./, '');
+    // Check if already present
+    if (ctXml.includes(`Extension="${extNoDot}"`))
+        return;
+    const ctDom = new DOMParser().parseFromString(ctXml, 'application/xml');
+    const types = ctDom.documentElement;
+    const defaultEl = ctDom.createElement('Default');
+    defaultEl.setAttribute('Extension', extNoDot);
+    defaultEl.setAttribute('ContentType', getMimeType(ext));
+    types.appendChild(defaultEl);
+    const newCtXml = new XMLSerializer().serializeToString(ctDom);
+    zip.file(ctPath, newCtXml);
+}