@wonderwhy-er/desktop-commander 0.2.35 → 0.2.37

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

@@ -1,114 +1,213 @@
 /**
- * DOCX Type Definitions
- *
- * Centralised type definitions for every DOCX operation in the module.
- *
- * @module docx/types
+ * Type definitions for DOCX operations.
+ * Single source of truth for every type used across the DOCX module.
  */
-/** Default font and size extracted from the original DOCX, used to preserve styles on re-creation. */
-export interface DocxDocumentDefaults {
-    /** Default font family (e.g. 'Calibri', 'Times New Roman') */
-    font: string;
-    /** Default font size in points (e.g. 11, 12) */
-    fontSize: number;
-}
 export interface DocxMetadata {
     title?: string;
     author?: string;
     subject?: string;
-    description?: string;
-    creationDate?: Date;
-    modificationDate?: Date;
-    lastModifiedBy?: string;
-    revision?: string;
-    fileSize?: number;
-}
-export interface DocxImage {
-    id: string;
-    /** Base64-encoded image data */
-    data: string;
-    mimeType: string;
+    creator?: string;
+    paragraphCount: number;
+    wordCount: number;
+}
+export interface DocxParagraph {
+    index: number;
+    text: string;
+    hasText: boolean;
+}
+export interface DocxRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    fontSize?: number;
+    fontName?: string;
+}
+export interface DocxModification {
+    type: 'replace' | 'insert' | 'delete' | 'style';
+    paragraphIndex?: number;
+    findText?: string;
+    replaceText?: string;
+    insertText?: string;
+    style?: {
+        color?: string;
+        bold?: boolean;
+        italic?: boolean;
+    };
+}
+export interface ParagraphOutline {
+    bodyChildIndex: number;
+    paragraphIndex: number;
+    style: string | null;
+    text: string;
+}
+export interface TableOutline {
+    bodyChildIndex: number;
+    tableIndex: number;
+    style: string | null;
+    headers?: string[];
+    rows: string[][];
+}
+export interface ImageOutline {
+    bodyChildIndex: number;
+    imageIndex: number;
+    mediaPath: string;
+    rId: string;
     altText?: string;
-    originalSize?: number;
-}
-export interface DocxSection {
-    type: 'heading' | 'paragraph' | 'list' | 'table' | 'image';
-    content: string;
-    level?: number;
-    images?: DocxImage[];
-}
-export interface DocxParseResult {
-    html: string;
-    metadata: DocxMetadata;
-    images: DocxImage[];
-    sections?: DocxSection[];
-    /** Original document defaults — passed through the pipeline to preserve styles during editing. */
-    documentDefaults?: DocxDocumentDefaults;
-}
-export interface DocxParseOptions {
-    includeImages?: boolean;
-    preserveFormatting?: boolean;
-    styleMap?: string[];
-}
-export interface DocxBuildOptions {
-    baseDir?: string;
-    includeImages?: boolean;
-    preserveFormatting?: boolean;
-    /** Original document defaults to preserve font/size when converting HTML → DOCX. */
-    documentDefaults?: DocxDocumentDefaults;
-}
-export interface DocxEditOptions extends DocxBuildOptions {
-    outputPath?: string;
-    styleMap?: string[];
-}
-export interface DocxReplaceTextOperation {
-    type: 'replaceText';
-    search: string;
-    replace: string;
-    matchCase?: boolean;
-    global?: boolean;
-}
-export interface DocxAppendMarkdownOperation {
-    type: 'appendMarkdown';
-    markdown: string;
-}
-export interface DocxInsertTableOperation {
-    type: 'insertTable';
-    markdownTable?: string;
-    rows?: string[][];
-    selector?: string;
-    position?: 'before' | 'after' | 'inside';
-}
-export interface DocxInsertImageOperation {
-    type: 'insertImage';
+}
+export interface ReadDocxResult {
+    path: string;
+    paragraphs: ParagraphOutline[];
+    tables: TableOutline[];
+    images: ImageOutline[];
+    stylesSeen: string[];
+    counts: {
+        tables: number;
+        images: number;
+        bodyChildren: number;
+    };
+}
+export interface WriteDocxStats {
+    tablesBefore: number;
+    tablesAfter: number;
+    bodyChildrenBefore: number;
+    bodyChildrenAfter: number;
+    bodySignatureBefore: string;
+    bodySignatureAfter: string;
+}
+export interface WriteDocxResult {
+    outputPath: string;
+    results: OpResult[];
+    stats: WriteDocxStats;
+    warnings: string[];
+}
+export interface BodySnapshot {
+    bodyChildCount: number;
+    tableCount: number;
+    signature: string;
+}
+export interface ReplaceParagraphTextExactOp {
+    type: 'replace_paragraph_text_exact';
+    from: string;
+    to: string;
+}
+export interface ReplaceParagraphAtBodyIndexOp {
+    type: 'replace_paragraph_at_body_index';
+    bodyChildIndex: number;
+    to: string;
+}
+export interface SetColorForStyleOp {
+    type: 'set_color_for_style';
+    style: string;
+    color: string;
+}
+export interface SetColorForParagraphExactOp {
+    type: 'set_color_for_paragraph_exact';
+    text: string;
+    color: string;
+}
+export interface SetParagraphStyleAtBodyIndexOp {
+    type: 'set_paragraph_style_at_body_index';
+    bodyChildIndex: number;
+    style: string;
+}
+export interface InsertParagraphAfterTextOp {
+    type: 'insert_paragraph_after_text';
+    after: string;
+    text: string;
+    style?: string;
+}
+export interface DeleteParagraphAtBodyIndexOp {
+    type: 'delete_paragraph_at_body_index';
+    bodyChildIndex: number;
+}
+export interface TableSetCellTextOp {
+    type: 'table_set_cell_text';
+    tableIndex: number;
+    row: number;
+    col: number;
+    text: string;
+}
+export interface ReplaceTableCellTextOp {
+    type: 'replace_table_cell_text';
+    from: string;
+    to: string;
+}
+export interface ReplaceHyperlinkUrlOp {
+    type: 'replace_hyperlink_url';
+    oldUrl: string;
+    newUrl: string;
+}
+export interface HeaderReplaceTextExactOp {
+    type: 'header_replace_text_exact';
+    from: string;
+    to: string;
+}
+export interface InsertTableOp {
+    type: 'insert_table';
+    /** Exact trimmed text of the paragraph to insert AFTER. Mutually exclusive with `before`. */
+    after?: string;
+    /** Exact trimmed text of the paragraph to insert BEFORE. Mutually exclusive with `after`. */
+    before?: string;
+    /** Optional header row (bold cells) */
+    headers?: string[];
+    /** Data rows — each row is an array of cell strings */
+    rows: string[][];
+    /** Optional column widths in twips (1/20 pt). Defaults to auto. */
+    colWidths?: number[];
+    /** Optional table style id (e.g. 'TableGrid') */
+    style?: string;
+}
+export interface InsertImageOp {
+    type: 'insert_image';
+    /** Exact trimmed text of the paragraph to insert AFTER. Mutually exclusive with `before`. */
+    after?: string;
+    /** Exact trimmed text of the paragraph to insert BEFORE. Mutually exclusive with `after`. */
+    before?: string;
+    /** Absolute or relative path to the image file */
     imagePath: string;
+    /** Image width in pixels (default 300) */
+    width?: number;
+    /** Image height in pixels (default 200) */
+    height?: number;
+    /** Alt text for accessibility */
     altText?: string;
+}
+export type DocxOp = ReplaceParagraphTextExactOp | ReplaceParagraphAtBodyIndexOp | SetColorForStyleOp | SetColorForParagraphExactOp | SetParagraphStyleAtBodyIndexOp | InsertParagraphAfterTextOp | DeleteParagraphAtBodyIndexOp | TableSetCellTextOp | ReplaceTableCellTextOp | ReplaceHyperlinkUrlOp | HeaderReplaceTextExactOp | InsertTableOp | InsertImageOp;
+export interface OpResult {
+    op: DocxOp;
+    status: 'applied' | 'skipped';
+    matched: number;
+    reason?: string;
+}
+export interface DocxContentParagraph {
+    type: 'paragraph';
+    text: string;
+    style?: string | null;
+}
+/**
+ * Cell content can be:
+ * - A string (simple case, creates one paragraph)
+ * - An array of paragraphs (allows multiple paragraphs with different styles per cell)
+ */
+export type DocxTableCellContent = string | DocxContentParagraph[];
+export interface DocxContentTable {
+    type: 'table';
+    /** Header cells - can be strings or arrays of paragraphs */
+    headers?: DocxTableCellContent[];
+    /** Data rows - each cell can be a string or array of paragraphs */
+    rows: DocxTableCellContent[][];
+    colWidths?: number[];
+    style?: string;
+}
+export interface DocxContentImage {
+    type: 'image';
+    imagePath: string;
     width?: number;
     height?: number;
-    selector?: string;
-    position?: 'before' | 'after' | 'inside';
-}
-export interface DocxAppendHtmlOperation {
-    type: 'appendHtml';
-    html: string;
-}
-export interface DocxInsertHtmlOperation {
-    type: 'insertHtml';
-    html: string;
-    selector?: string;
-    position?: 'before' | 'after' | 'inside';
-}
-export interface DocxReplaceHtmlOperation {
-    type: 'replaceHtml';
-    selector: string;
-    html: string;
-    replaceAll?: boolean;
-}
-export interface DocxUpdateHtmlOperation {
-    type: 'updateHtml';
-    selector: string;
-    html?: string;
-    attributes?: Record<string, string>;
-    updateAll?: boolean;
-}
-export type DocxOperation = DocxReplaceTextOperation | DocxAppendMarkdownOperation | DocxInsertTableOperation | DocxInsertImageOperation | DocxAppendHtmlOperation | DocxInsertHtmlOperation | DocxReplaceHtmlOperation | DocxUpdateHtmlOperation;
+    altText?: string;
+}
+export type DocxContentItem = DocxContentParagraph | DocxContentTable | DocxContentImage;
+export interface DocxContentStructure {
+    items: DocxContentItem[];
+}

package/dist/tools/docx/types.js

@@ -1,8 +1,5 @@
 /**
- * DOCX Type Definitions
- *
- * Centralised type definitions for every DOCX operation in the module.
- *
- * @module docx/types
+ * Type definitions for DOCX operations.
+ * Single source of truth for every type used across the DOCX module.
  */
 export {};

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

@@ -0,0 +1,33 @@
+/**
+ * Invariant validation for DOCX write operations.
+ *
+ * Single Responsibility: capture a structural snapshot of w:body and
+ * compare before / after snapshots to guarantee no accidental breakage.
+ */
+import type { BodySnapshot } from './types.js';
+export interface ValidationOptions {
+    /**
+     * Expected change in w:body direct child count.
+     * Positive = inserts, negative = deletes.
+     * Default 0 (no structural changes expected).
+     */
+    expectedChildDelta?: number;
+    /**
+     * Expected change in w:tbl count.
+     * Default 0 (no table additions/removals expected).
+     */
+    expectedTableDelta?: number;
+}
+/** Take a snapshot of the body's structural invariants. */
+export declare function captureSnapshot(body: Element): BodySnapshot;
+/**
+ * Compare before / after snapshots.
+ * Throws a descriptive error if any invariant has been violated,
+ * preventing the output file from being written.
+ *
+ * When `expectedChildDelta` is non-zero (structural ops like insert or
+ * delete), signature validation is skipped because the body structure
+ * is *expected* to change.  Child count is still validated against
+ * the expected delta, and table count must remain unchanged.
+ */
+export declare function validateInvariants(before: BodySnapshot, after: BodySnapshot, options?: ValidationOptions): void;

package/dist/tools/docx/validate.js

@@ -0,0 +1,49 @@
+/**
+ * Invariant validation for DOCX write operations.
+ *
+ * Single Responsibility: capture a structural snapshot of w:body and
+ * compare before / after snapshots to guarantee no accidental breakage.
+ */
+import { getBodyChildren, bodySignature, countTables } from './dom.js';
+// ─── Capture ─────────────────────────────────────────────────────────
+/** Take a snapshot of the body's structural invariants. */
+export function captureSnapshot(body) {
+    const children = getBodyChildren(body);
+    return {
+        bodyChildCount: children.length,
+        tableCount: countTables(children),
+        signature: bodySignature(children),
+    };
+}
+// ─── Validate ────────────────────────────────────────────────────────
+/**
+ * Compare before / after snapshots.
+ * Throws a descriptive error if any invariant has been violated,
+ * preventing the output file from being written.
+ *
+ * When `expectedChildDelta` is non-zero (structural ops like insert or
+ * delete), signature validation is skipped because the body structure
+ * is *expected* to change.  Child count is still validated against
+ * the expected delta, and table count must remain unchanged.
+ */
+export function validateInvariants(before, after, options) {
+    const delta = options?.expectedChildDelta ?? 0;
+    const tableDelta = options?.expectedTableDelta ?? 0;
+    const expectedChildCount = before.bodyChildCount + delta;
+    const expectedTableCount = before.tableCount + tableDelta;
+    const errors = [];
+    if (expectedChildCount !== after.bodyChildCount) {
+        errors.push(`Body child count mismatch: expected ${expectedChildCount} (before ${before.bodyChildCount} + delta ${delta}), got ${after.bodyChildCount}`);
+    }
+    if (expectedTableCount !== after.tableCount) {
+        errors.push(`Table count mismatch: expected ${expectedTableCount} (before ${before.tableCount} + delta ${tableDelta}), got ${after.tableCount}`);
+    }
+    // Only enforce signature stability when no structural ops changed the body
+    if (delta === 0 && before.signature !== after.signature) {
+        errors.push(`Body signature changed:\n  before: ${before.signature}\n  after:  ${after.signature}`);
+    }
+    if (errors.length > 0) {
+        throw new Error('DOCX structural validation failed — output NOT written.\n' +
+            errors.join('\n'));
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * writeDocxPatched - the patch-based "update" orchestrator.
+ *
+ * Single Responsibility: coordinate the full update pipeline:
+ *   1. Open DOCX ZIP
+ *   2. Parse word/document.xml
+ *   3. Snapshot before
+ *   4. Apply operations (pass zip for ops that touch auxiliary files)
+ *   5. Snapshot after
+ *   6. Validate invariants (accounting for structural deltas)
+ *   7. Serialize and save
+ *
+ * Each step delegates to a single-purpose module, keeping this file
+ * a pure orchestrator with no direct DOM/XML/ZIP logic.
+ */
+import type { DocxOp, WriteDocxResult } from './types.js';
+export declare function writeDocxPatched(inputPath: string, outputPath: string, ops: DocxOp[]): Promise<WriteDocxResult>;

package/dist/tools/docx/write.js

@@ -0,0 +1,88 @@
+/**
+ * writeDocxPatched - the patch-based "update" orchestrator.
+ *
+ * Single Responsibility: coordinate the full update pipeline:
+ *   1. Open DOCX ZIP
+ *   2. Parse word/document.xml
+ *   3. Snapshot before
+ *   4. Apply operations (pass zip for ops that touch auxiliary files)
+ *   5. Snapshot after
+ *   6. Validate invariants (accounting for structural deltas)
+ *   7. Serialize and save
+ *
+ * Each step delegates to a single-purpose module, keeping this file
+ * a pure orchestrator with no direct DOM/XML/ZIP logic.
+ */
+import { loadDocxZip, getDocumentXml, saveDocxZip } from './zip.js';
+import { parseXml, serializeXml, getBody } from './dom.js';
+import { captureSnapshot, validateInvariants } from './validate.js';
+import { applyOp } from './ops/index.js';
+/** Structural op types that add/remove body children. */
+const STRUCTURAL_INSERT_OPS = new Set([
+    'insert_paragraph_after_text',
+    'insert_table',
+    'insert_image',
+]);
+const STRUCTURAL_DELETE_OPS = new Set(['delete_paragraph_at_body_index']);
+export async function writeDocxPatched(inputPath, outputPath, ops) {
+    // 1. Load ZIP
+    const zip = await loadDocxZip(inputPath);
+    // 2. Parse document.xml
+    const xmlStr = getDocumentXml(zip);
+    const doc = parseXml(xmlStr);
+    const body = getBody(doc);
+    // 3. Before-snapshot
+    const before = captureSnapshot(body);
+    // 4. Apply ops — pass zip for ops that modify auxiliary files
+    const results = [];
+    const warnings = [];
+    for (const op of ops) {
+        try {
+            const result = applyOp(body, op, zip);
+            results.push(result);
+            if (result.status === 'skipped') {
+                warnings.push(`Op ${op.type} skipped: ${result.reason ?? 'unknown'}`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`Op ${op.type} failed: ${msg}`);
+            results.push({
+                op,
+                status: 'skipped',
+                matched: 0,
+                reason: `error: ${msg}`,
+            });
+        }
+    }
+    // 5. Compute expected structural delta from applied ops
+    let expectedChildDelta = 0;
+    let expectedTableDelta = 0;
+    for (const r of results) {
+        if (r.status !== 'applied')
+            continue;
+        if (STRUCTURAL_INSERT_OPS.has(r.op.type))
+            expectedChildDelta += 1;
+        if (STRUCTURAL_DELETE_OPS.has(r.op.type))
+            expectedChildDelta -= 1;
+        if (r.op.type === 'insert_table')
+            expectedTableDelta += 1;
+    }
+    // 6. After-snapshot
+    const after = captureSnapshot(body);
+    // 7. Validate — throws if structural invariants are broken
+    validateInvariants(before, after, { expectedChildDelta, expectedTableDelta });
+    // 8. Serialize and save (document.xml + any zip-level changes)
+    const newXml = serializeXml(doc);
+    await saveDocxZip(zip, newXml, outputPath);
+    // 9. Build stats
+    const stats = {
+        tablesBefore: before.tableCount,
+        tablesAfter: after.tableCount,
+        bodyChildrenBefore: before.bodyChildCount,
+        bodyChildrenAfter: after.bodyChildCount,
+        bodySignatureBefore: before.signature,
+        bodySignatureAfter: after.signature,
+    };
+    return { outputPath, results, stats, warnings };
+}

package/dist/tools/docx/xml-view-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/docx/xml-view-test.js

@@ -0,0 +1,63 @@
+/**
+ * Quick test: extract XML, show context, then edit a checkbox.
+ */
+import { extractDocxXml, editDocxXml } from './xml-view.js';
+async function main() {
+    const input = '/Users/eduardsruzga/Downloads/dcox/Wedding Photo Checklist.docx';
+    const output = '/Users/eduardsruzga/Downloads/dcox/Wedding Photo Checklist - XML Edit Test.docx';
+    // 1. Extract and show stats
+    const view = await extractDocxXml(input);
+    console.log(`Extracted XML: ${view.lineCount} lines, ${view.rawSize} raw chars`);
+    // 2. Show context around "Bride hairstyling" with EXACT indentation
+    const lines = view.xml.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes('Bride hairstyling')) {
+            console.log(`\nFound "Bride hairstyling" at line ${i + 1}:`);
+            for (let j = Math.max(0, i - 20); j <= Math.min(lines.length - 1, i + 5); j++) {
+                console.log(`${String(j + 1).padStart(4)}|${lines[j]}`);
+            }
+            // 3. Build the old/new strings from ACTUAL lines
+            // The ☐ should be around line i-20 to i-15
+            // Find it by scanning backwards
+            let checkboxLine = -1;
+            for (let j = i - 1; j >= Math.max(0, i - 25); j--) {
+                if (lines[j].includes('☐')) {
+                    checkboxLine = j;
+                    break;
+                }
+            }
+            console.log(`\nCheckbox ☐ found at line ${checkboxLine + 1}: "${lines[checkboxLine]}"`);
+            // Use just enough context: the checkbox line + next line to make it unique
+            const oldStr = lines[checkboxLine];
+            const newStr = oldStr.replace('☐', '☑');
+            console.log(`\nold: "${oldStr}"`);
+            console.log(`new: "${newStr}"`);
+            // Check uniqueness
+            const matches = lines.filter(l => l === oldStr).length;
+            console.log(`Exact line matches in document: ${matches}`);
+            if (matches > 1) {
+                // Expand context until we get exactly 1 match
+                for (let ctx = 3; ctx <= 30; ctx++) {
+                    const contextOld = lines.slice(checkboxLine, checkboxLine + ctx).join('\n');
+                    const contextMatches = view.xml.split(contextOld).length - 1;
+                    if (contextMatches === 1) {
+                        console.log(`\nUnique match found with ${ctx}-line context`);
+                        const contextNew = contextOld.replace('☐', '☑');
+                        const result = await editDocxXml(input, output, contextOld, contextNew);
+                        console.log(`Edit result:`, result);
+                        break;
+                    }
+                    else {
+                        console.log(`${ctx} lines of context: ${contextMatches} matches`);
+                    }
+                }
+            }
+            else {
+                const result = await editDocxXml(input, output, oldStr, newStr);
+                console.log(`\nEdit result:`, result);
+            }
+            break;
+        }
+    }
+}
+main().catch(console.error);

package/dist/tools/docx/xml-view.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DOCX XML View
+ *
+ * Exposes word/document.xml from a DOCX file as pretty-printed XML that can be
+ * read with offset/length pagination and edited with find/replace, just like a
+ * text file. All formatting is preserved because we operate on the actual XML.
+ *
+ * Round-trip: DOCX → unzip → pretty-print → edit → compact → repack → DOCX
+ */
+/**
+ * Pretty-print XML by splitting tags onto separate lines with indentation.
+ *
+ * Preserves content inside text nodes exactly. Self-closing tags, inline
+ * open+close tags (e.g. <w:t>text</w:t>), and pure closing tags are all
+ * handled so that compact→pretty→compact is lossless.
+ */
+export declare function prettyPrintXml(xml: string): string;
+/**
+ * Compact pretty-printed XML back to a single line.
+ *
+ * CRITICAL: Must not introduce or remove whitespace inside <w:t> text nodes
+ * or break xml:space="preserve" semantics. We achieve this by only stripping
+ * leading indentation (which we added) and joining lines. The original XML
+ * had no newlines between tags, so this restores the original form.
+ */
+export declare function compactXml(prettyXml: string): string;
+export interface DocxXmlReadResult {
+    /** Pretty-printed XML content */
+    content: string;
+    /** Total number of lines */
+    lineCount: number;
+    /** Source DOCX path */
+    path: string;
+    /** Size of the raw (compact) XML in chars */
+    rawSize: number;
+}
+/**
+ * Read the document.xml from a DOCX as pretty-printed, line-based XML.
+ * Supports offset/length pagination just like text file reading.
+ */
+export declare function readDocxXml(filePath: string, offset?: number, length?: number): Promise<DocxXmlReadResult>;
+/**
+ * Apply a find/replace edit to a DOCX file's XML and write a new DOCX.
+ *
+ * The edit operates on the pretty-printed XML so that line-based context
+ * from read_file can be used directly as the search string. After editing,
+ * the XML is compacted back and repacked into the DOCX zip.
+ *
+ * @returns result with status, match count, and output path
+ */
+export declare function editDocxXml(inputPath: string, outputPath: string, oldStr: string, newStr: string, expectedReplacements?: number): Promise<{
+    status: 'applied' | 'no_match' | 'unexpected_count';
+    matchCount: number;
+    outputPath: string;
+    message?: string;
+}>;