@wonderwhy-er/desktop-commander 0.2.35 → 0.2.36

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

@@ -1,114 +1,184 @@
 /**
- * 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;
-    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';
+    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 ReadDocxResult {
+    path: string;
+    paragraphs: ParagraphOutline[];
+    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 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 | 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;
+}
+export interface DocxContentTable {
+    type: 'table';
+    headers?: string[];
+    rows: string[][];
+    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/zip.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DOCX ZIP I/O — Single Responsibility: file ↔ zip ↔ xml.
+ *
+ * Every other module depends on these three functions for disk I/O;
+ * none of them touch the file system directly.
+ */
+import PizZip from 'pizzip';
+/**
+ * Read a .docx file from disk and return a PizZip instance.
+ */
+export declare function loadDocxZip(filePath: string): Promise<PizZip>;
+/**
+ * Extract the raw XML string from word/document.xml inside the zip.
+ * Throws if the entry is missing.
+ */
+export declare function getDocumentXml(zip: PizZip): string;
+/**
+ * Replace word/document.xml in the zip with new XML,
+ * then write the whole archive to outputPath.
+ */
+export declare function saveDocxZip(zip: PizZip, newDocumentXml: string, outputPath: string): Promise<void>;

package/dist/tools/docx/zip.js

@@ -0,0 +1,35 @@
+/**
+ * DOCX ZIP I/O — Single Responsibility: file ↔ zip ↔ xml.
+ *
+ * Every other module depends on these three functions for disk I/O;
+ * none of them touch the file system directly.
+ */
+import fs from 'fs/promises';
+import PizZip from 'pizzip';
+/**
+ * Read a .docx file from disk and return a PizZip instance.
+ */
+export async function loadDocxZip(filePath) {
+    const buf = await fs.readFile(filePath);
+    return new PizZip(buf);
+}
+/**
+ * Extract the raw XML string from word/document.xml inside the zip.
+ * Throws if the entry is missing.
+ */
+export function getDocumentXml(zip) {
+    const entry = zip.file('word/document.xml');
+    if (!entry) {
+        throw new Error('Invalid DOCX: missing word/document.xml');
+    }
+    return entry.asText();
+}
+/**
+ * Replace word/document.xml in the zip with new XML,
+ * then write the whole archive to outputPath.
+ */
+export async function saveDocxZip(zip, newDocumentXml, outputPath) {
+    zip.file('word/document.xml', newDocumentXml);
+    const buf = zip.generate({ type: 'nodebuffer' });
+    await fs.writeFile(outputPath, buf);
+}

package/dist/tools/schemas.d.ts

@@ -401,3 +401,16 @@ export declare const GetRecentToolCallsArgsSchema: z.ZodObject<{
     toolName?: string | undefined;
     since?: string | undefined;
 }>;
+export declare const TrackUiEventArgsSchema: z.ZodObject<{
+    event: z.ZodString;
+    component: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    params: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>>;
+}, "strip", z.ZodTypeAny, {
+    params: Record<string, string | number | boolean | null>;
+    event: string;
+    component: string;
+}, {
+    event: string;
+    params?: Record<string, string | number | boolean | null> | undefined;
+    component?: string | undefined;
+}>;

package/dist/tools/schemas.js

@@ -175,3 +175,8 @@ export const GetRecentToolCallsArgsSchema = z.object({
     toolName: z.string().optional(),
     since: z.string().datetime().optional(),
 });
+export const TrackUiEventArgsSchema = z.object({
+    event: z.string().min(1).max(80),
+    component: z.string().optional().default('file_preview'),
+    params: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional().default({}),
+});

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import { ChildProcess } from 'child_process';
 import { FilteredStdioServerTransport } from './custom-stdio.js';
+import type { PreviewFileType } from './ui/file-preview/shared/preview-file-types.js';
 declare global {
     var mcpTransport: FilteredStdioServerTransport | undefined;
     var disableOnboarding: boolean | undefined;
@@ -60,8 +61,17 @@ export interface ServerResponseContent {
     data?: string;
     mimeType?: string;
 }
+export interface FilePreviewStructuredContent {
+    fileName: string;
+    filePath: string;
+    fileType: PreviewFileType;
+    content: string;
+    imageData?: string;
+    mimeType?: string;
+}
 export interface ServerResult {
     content: ServerResponseContent[];
+    structuredContent?: FilePreviewStructuredContent | Record<string, unknown>;
     isError?: boolean;
     _meta?: Record<string, unknown>;
 }

package/dist/ui/contracts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Central constants and shape contracts for UI resource identifiers. It gives one source of truth for URIs/tool metadata shared between server handlers and UI loaders.
+ */
+export declare const FILE_PREVIEW_RESOURCE_URI = "ui://desktop-commander/file-preview";
+export declare const CONFIG_EDITOR_RESOURCE_URI = "ui://desktop-commander/config-editor";
+export interface UiToolMeta extends Record<string, unknown> {
+    'ui/resourceUri': string;
+    'openai/outputTemplate': string;
+    ui: {
+        resourceUri: string;
+    };
+    'openai/widgetAccessible'?: boolean;
+}
+export declare function buildUiToolMeta(resourceUri: string, widgetAccessible?: boolean): UiToolMeta;

package/dist/ui/contracts.js

@@ -0,0 +1,18 @@
+/**
+ * Central constants and shape contracts for UI resource identifiers. It gives one source of truth for URIs/tool metadata shared between server handlers and UI loaders.
+ */
+export const FILE_PREVIEW_RESOURCE_URI = 'ui://desktop-commander/file-preview';
+export const CONFIG_EDITOR_RESOURCE_URI = 'ui://desktop-commander/config-editor';
+export function buildUiToolMeta(resourceUri, widgetAccessible = false) {
+    const meta = {
+        'ui/resourceUri': resourceUri,
+        'openai/outputTemplate': resourceUri,
+        ui: {
+            resourceUri,
+        },
+    };
+    if (widgetAccessible) {
+        meta['openai/widgetAccessible'] = true;
+    }
+    return meta;
+}

package/dist/ui/file-preview/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<!--
+  Host page for the File Preview MCP UI. It establishes the root structure and script/style loading required to render text, markdown, and HTML previews safely.
+-->
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Desktop Commander File Preview</title>
+  <link rel="stylesheet" href="./styles.css" />
+</head>
+<body>
+  <div id="app"></div>
+  <script src="./preview-runtime.js"></script>
+</body>
+</html>