@wonderwhy-er/desktop-commander 0.2.35 → 0.2.37

package/dist/ui/resources.d.ts

@@ -0,0 +1,21 @@
+export declare const FILE_PREVIEW_RESOURCE: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+};
+export declare function getFilePreviewResourceText(): Promise<string>;
+export declare function listUiResources(): {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function readUiResource(uri: string): Promise<{
+    contents: {
+        _meta?: Record<string, unknown> | undefined;
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+} | null>;

package/dist/ui/resources.js

@@ -0,0 +1,72 @@
+/**
+ * Server-side UI resource loading helpers for MCP responses. It resolves packaged UI assets, reads files safely, and exposes structured resource payloads to clients.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { FILE_PREVIEW_RESOURCE_URI } from './contracts.js';
+const UI_RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app';
+export const FILE_PREVIEW_RESOURCE = {
+    uri: FILE_PREVIEW_RESOURCE_URI,
+    name: 'Desktop Commander File Preview',
+    description: 'Markdown-first preview surface for read_file structured content.',
+    mimeType: UI_RESOURCE_MIME_TYPE
+};
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DIST_FILE_PREVIEW_DIR = path.resolve(__dirname, 'file-preview');
+function replaceOrThrow(source, pattern, replacement, context) {
+    if (!pattern.test(source)) {
+        throw new Error(`UI template is missing expected ${context}`);
+    }
+    return source.replace(pattern, () => replacement);
+}
+function inlineTemplateAssets(templateHtml, css, runtime) {
+    const safeCss = css.replace(/<\/style/gi, '<\\/style');
+    const safeRuntime = runtime.replace(/<\/script/gi, '<\\/script');
+    const cssInlined = replaceOrThrow(templateHtml, /<link[^>]*href=["']\.\/styles\.css["'][^>]*>/i, `<style>${safeCss}</style>`, 'styles.css link tag');
+    const runtimeInlined = replaceOrThrow(cssInlined, /<script[^>]*src=["']\.\/[^"']+["'][^>]*>\s*<\/script>/i, `<script>${safeRuntime}</script>`, 'runtime script tag');
+    if (/href=["']\.\/styles\.css["']/i.test(runtimeInlined) ||
+        /<script[^>]*src=["']\.\/[^"']+["']/i.test(runtimeInlined)) {
+        throw new Error('UI template still contains external static asset references after inlining');
+    }
+    return runtimeInlined;
+}
+async function readInlinedResourceHtml(distDir, runtimeFileName) {
+    const [templateHtml, css, runtime] = await Promise.all([
+        fs.readFile(path.join(distDir, 'index.html'), 'utf8'),
+        fs.readFile(path.join(distDir, 'styles.css'), 'utf8'),
+        fs.readFile(path.join(distDir, runtimeFileName), 'utf8')
+    ]);
+    return inlineTemplateAssets(templateHtml, css, runtime);
+}
+export async function getFilePreviewResourceText() {
+    return readInlinedResourceHtml(DIST_FILE_PREVIEW_DIR, 'preview-runtime.js');
+}
+const READABLE_UI_RESOURCES = {
+    [FILE_PREVIEW_RESOURCE_URI]: {
+        mimeType: FILE_PREVIEW_RESOURCE.mimeType,
+        getText: getFilePreviewResourceText
+    }
+};
+export function listUiResources() {
+    return [FILE_PREVIEW_RESOURCE];
+}
+export async function readUiResource(uri) {
+    const resource = READABLE_UI_RESOURCES[uri];
+    if (!resource) {
+        return null;
+    }
+    const resourceText = await resource.getText();
+    const resourceMeta = resource.getMeta?.();
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: resource.mimeType,
+                text: resourceText,
+                ...(resourceMeta ? { _meta: resourceMeta } : {})
+            }
+        ]
+    };
+}

package/dist/ui/shared/escape-html.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared HTML escaping helper for UI string interpolation.
+ */
+export declare function escapeHtml(value: string): string;

package/dist/ui/shared/escape-html.js

@@ -0,0 +1,11 @@
+/**
+ * Shared HTML escaping helper for UI string interpolation.
+ */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

package/dist/ui/shared/host-lifecycle.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cross-tool lifecycle helpers for host readiness, teardown, and event subscriptions. It standardizes app lifecycle behavior across UI surfaces.
+ */
+import type { RpcClient } from './rpc-client.js';
+interface UiHostLifecycleOptions {
+    appName: string;
+    appVersion?: string;
+    getRootElement?: () => Element | null;
+}
+export interface UiHostLifecycle {
+    notifyRender: () => void;
+    observeResize: () => void;
+    initialize: () => void;
+}
+export declare function createUiHostLifecycle(rpcClient: RpcClient, options: UiHostLifecycleOptions): UiHostLifecycle;
+export {};

package/dist/ui/shared/host-lifecycle.js

@@ -0,0 +1,35 @@
+export function createUiHostLifecycle(rpcClient, options) {
+    const { appName, appVersion = '1.0.0', getRootElement } = options;
+    const resolveRootElement = () => getRootElement?.() ?? (document.getElementById('app')?.firstElementChild ?? document.getElementById('app'));
+    const notifySizeChanged = () => {
+        const node = resolveRootElement();
+        const height = Math.max(28, Math.ceil(node?.getBoundingClientRect().height ?? 0));
+        rpcClient.notify('ui/notifications/size-changed', { height });
+    };
+    return {
+        notifyRender: () => {
+            notifySizeChanged();
+            setTimeout(notifySizeChanged, 80);
+        },
+        observeResize: () => {
+            if (!window.ResizeObserver) {
+                return;
+            }
+            const observer = new ResizeObserver(() => notifySizeChanged());
+            observer.observe(document.documentElement);
+        },
+        initialize: () => {
+            void rpcClient.request('ui/initialize', {
+                appInfo: { name: appName, version: appVersion },
+                appCapabilities: {},
+                protocolVersion: '2026-01-26',
+            }).then(() => {
+                rpcClient.notify('ui/notifications/initialized', {});
+            }).catch(() => {
+                // Initialization handshake failure should not break rendering.
+                // Still send initialized in case host is lenient.
+                rpcClient.notify('ui/notifications/initialized', {});
+            });
+        },
+    };
+}

package/dist/ui/shared/rpc-client.d.ts

@@ -0,0 +1,14 @@
+export interface RpcClient {
+    notify: (method: string, params: Record<string, unknown>) => void;
+    request: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+    handleMessageEvent: (event: MessageEvent) => boolean;
+    dispose: () => void;
+}
+export interface RpcClientOptions {
+    targetWindow: Window;
+    targetOrigin?: string;
+    timeoutMs?: number;
+    isTrustedSource?: (source: MessageEvent['source'] | null) => boolean;
+}
+export declare function isTrustedParentMessageSource(source: MessageEvent['source'] | null, expectedSource: Window): boolean;
+export declare function createWindowRpcClient(options: RpcClientOptions): RpcClient;

package/dist/ui/shared/rpc-client.js

@@ -0,0 +1,72 @@
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isTrustedParentMessageSource(source, expectedSource) {
+    return source === expectedSource;
+}
+export function createWindowRpcClient(options) {
+    const { targetWindow, targetOrigin = '*', timeoutMs = 15000, isTrustedSource = () => true, } = options;
+    let requestId = 1;
+    const pendingRequests = new Map();
+    const postMessage = (payload) => {
+        targetWindow.postMessage(payload, targetOrigin);
+    };
+    const notify = (method, params) => {
+        postMessage({
+            jsonrpc: '2.0',
+            method,
+            params,
+        });
+    };
+    const request = (method, params) => {
+        const id = requestId++;
+        postMessage({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pendingRequests.delete(id);
+                reject(new Error(`Request timed out for method ${method}`));
+            }, timeoutMs);
+            pendingRequests.set(id, { resolve, reject, timer });
+        });
+    };
+    const handleMessageEvent = (event) => {
+        if (!isTrustedSource(event.source)) {
+            return false;
+        }
+        if (!isObject(event.data) || typeof event.data.id !== 'number') {
+            return false;
+        }
+        const pending = pendingRequests.get(event.data.id);
+        if (!pending) {
+            return false;
+        }
+        clearTimeout(pending.timer);
+        pendingRequests.delete(event.data.id);
+        if (isObject(event.data.error)) {
+            const errorShape = event.data.error;
+            const message = typeof errorShape.message === 'string' ? errorShape.message : 'Unknown RPC error';
+            pending.reject(new Error(message));
+            return true;
+        }
+        pending.resolve(event.data.result);
+        return true;
+    };
+    const dispose = () => {
+        for (const [id, pending] of pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('RPC client disposed'));
+            pendingRequests.delete(id);
+        }
+    };
+    return {
+        notify,
+        request,
+        handleMessageEvent,
+        dispose,
+    };
+}

package/dist/ui/shared/theme-adaptation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Theme synchronization utilities that adapt embedded UI styles to host light/dark context. It centralizes theme event handling and class/token updates.
+ */
+type ThemeMode = 'light' | 'dark';
+export declare function resolveThemeMode(value: unknown): ThemeMode | undefined;
+export interface UiThemeAdapter {
+    applyFromData: (data: unknown) => boolean;
+}
+export declare function createUiThemeAdapter(root?: HTMLElement): UiThemeAdapter;
+export {};

package/dist/ui/shared/theme-adaptation.js

@@ -0,0 +1,118 @@
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function normalizeThemeMode(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'dark' || normalized === 'night') {
+        return 'dark';
+    }
+    if (normalized === 'light' || normalized === 'day') {
+        return 'light';
+    }
+    return undefined;
+}
+function pickThemeCandidate(value) {
+    if (!isObject(value)) {
+        return [];
+    }
+    const candidates = [
+        value.theme,
+        value.colorScheme,
+        value.appearance,
+        value.mode,
+    ];
+    if (isObject(value.context)) {
+        candidates.push(value.context, value.context.theme, value.context.colorScheme);
+    }
+    if (isObject(value.params)) {
+        candidates.push(value.params, value.params.theme, value.params.colorScheme, value.params.context);
+    }
+    return candidates;
+}
+export function resolveThemeMode(value) {
+    const direct = normalizeThemeMode(value);
+    if (direct) {
+        return direct;
+    }
+    if (!isObject(value)) {
+        return undefined;
+    }
+    for (const candidate of pickThemeCandidate(value)) {
+        const resolved = resolveThemeMode(candidate);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return undefined;
+}
+function isSafeCssVariableName(name) {
+    return /^--[a-zA-Z0-9_-]+$/.test(name);
+}
+function extractCssVariableMap(value) {
+    if (!isObject(value)) {
+        return {};
+    }
+    const params = isObject(value.params) ? value.params : undefined;
+    const paramsContext = params && isObject(params.context) ? params.context : undefined;
+    const rawMapCandidates = [
+        value.cssVariables,
+        value.variables,
+        value.tokens,
+        isObject(value.theme) ? value.theme.cssVariables : undefined,
+        isObject(value.theme) ? value.theme.variables : undefined,
+        isObject(value.theme) ? value.theme.tokens : undefined,
+        isObject(value.context) ? value.context.cssVariables : undefined,
+        isObject(value.context) ? value.context.variables : undefined,
+        isObject(value.context) ? value.context.tokens : undefined,
+        params ? params.cssVariables : undefined,
+        params ? params.variables : undefined,
+        params ? params.tokens : undefined,
+        paramsContext ? paramsContext.cssVariables : undefined,
+        paramsContext ? paramsContext.variables : undefined,
+        paramsContext ? paramsContext.tokens : undefined,
+    ];
+    for (const candidate of rawMapCandidates) {
+        if (!isObject(candidate)) {
+            continue;
+        }
+        const next = {};
+        for (const [rawKey, rawValue] of Object.entries(candidate)) {
+            if (typeof rawValue !== 'string') {
+                continue;
+            }
+            const key = rawKey.startsWith('--') ? rawKey : `--${rawKey}`;
+            if (!isSafeCssVariableName(key)) {
+                continue;
+            }
+            next[key] = rawValue.trim();
+        }
+        return next;
+    }
+    return {};
+}
+function applyCssVariables(root, variableMap) {
+    for (const [name, value] of Object.entries(variableMap)) {
+        root.style.setProperty(name, value);
+    }
+}
+export function createUiThemeAdapter(root = document.documentElement) {
+    const applyFromData = (data) => {
+        const mode = resolveThemeMode(data);
+        const variableMap = extractCssVariableMap(data);
+        const hasChanges = Boolean(mode) || Object.keys(variableMap).length > 0;
+        if (mode) {
+            root.dataset.theme = mode;
+            root.style.colorScheme = mode;
+        }
+        if (Object.keys(variableMap).length > 0) {
+            applyCssVariables(root, variableMap);
+        }
+        return hasChanges;
+    };
+    return {
+        applyFromData,
+    };
+}

package/dist/ui/shared/tool-header.d.ts

@@ -0,0 +1,9 @@
+export interface ToolHeaderConfig {
+    pillLabel: string;
+    pillClassName?: string;
+    title: string;
+    subtitle: string;
+    badges: string[];
+    actionsHtml: string;
+}
+export declare function renderToolHeader(config: ToolHeaderConfig): string;

package/dist/ui/shared/tool-header.js

@@ -0,0 +1,25 @@
+/**
+ * Reusable header renderer for MCP tool UIs. It provides a consistent title/description/status pattern so each app presents uniform top-of-page context.
+ */
+import { escapeHtml } from './escape-html.js';
+export function renderToolHeader(config) {
+    return `
+    <header class="toolbar">
+      <div class="meta">
+        <div class="meta-main">
+          <span class="file-pill ${escapeHtml(config.pillClassName ?? '')}">${escapeHtml(config.pillLabel)}</span>
+          <div class="meta-text">
+            <span class="filename" title="${escapeHtml(config.title)}">${escapeHtml(config.title)}</span>
+            <span class="filepath" title="${escapeHtml(config.subtitle)}">${escapeHtml(config.subtitle)}</span>
+          </div>
+        </div>
+        <div class="meta-badges">
+          ${config.badges.map((badge) => `<span class="badge">${escapeHtml(badge)}</span>`).join('')}
+        </div>
+      </div>
+      <div class="actions">
+        ${config.actionsHtml}
+      </div>
+    </header>
+  `;
+}

package/dist/ui/shared/tool-shell.d.ts

@@ -0,0 +1,16 @@
+export interface ToolShellController {
+    getExpanded: () => boolean;
+    setExpanded: (nextExpanded: boolean) => void;
+    toggle: () => void;
+    dispose: () => void;
+}
+interface CreateToolShellControllerOptions {
+    shell: HTMLElement | null;
+    toggleButton: HTMLButtonElement | null;
+    initialExpanded: boolean;
+    onToggle?: (expanded: boolean) => void;
+    onScrollAfterExpand?: () => void;
+    onRender?: () => void;
+}
+export declare function createToolShellController(options: CreateToolShellControllerOptions): ToolShellController;
+export {};

package/dist/ui/shared/tool-shell.js

@@ -0,0 +1,65 @@
+/**
+ * Shared shell behavior for collapsible sections and common UI affordances. It keeps repeated interaction patterns consistent across tool apps.
+ */
+const EXPAND_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M7 10l5 5 5-5z"></path></svg>';
+const COLLAPSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M7 14l5-5 5 5z"></path></svg>';
+function syncExpandButton(toggleButton, expanded) {
+    if (!toggleButton) {
+        return;
+    }
+    const label = expanded ? 'Collapse' : 'Expand';
+    toggleButton.title = label;
+    toggleButton.setAttribute('aria-label', label);
+    toggleButton.innerHTML = expanded ? COLLAPSE_ICON : EXPAND_ICON;
+}
+function syncShellClasses(shell, expanded) {
+    if (!shell) {
+        return;
+    }
+    shell.classList.toggle('expanded', expanded);
+    shell.classList.toggle('collapsed', !expanded);
+}
+export function createToolShellController(options) {
+    const { shell, toggleButton, initialExpanded, onToggle, onScrollAfterExpand, onRender } = options;
+    let isExpanded = initialExpanded;
+    let scrollTrackedForCurrentExpand = false;
+    const applyExpandedState = (nextExpanded) => {
+        const wasExpanded = isExpanded;
+        isExpanded = nextExpanded;
+        syncShellClasses(shell, isExpanded);
+        syncExpandButton(toggleButton, isExpanded);
+        if (!wasExpanded && isExpanded) {
+            scrollTrackedForCurrentExpand = false;
+        }
+    };
+    const toggle = () => {
+        applyExpandedState(!isExpanded);
+        onToggle?.(isExpanded);
+        onRender?.();
+    };
+    const handleScroll = (event) => {
+        if (!isExpanded || scrollTrackedForCurrentExpand) {
+            return;
+        }
+        const targetNode = event?.target instanceof Node ? event.target : null;
+        if (targetNode && shell && !shell.contains(targetNode)) {
+            return;
+        }
+        scrollTrackedForCurrentExpand = true;
+        onScrollAfterExpand?.();
+    };
+    applyExpandedState(isExpanded);
+    toggleButton?.addEventListener('click', toggle);
+    shell?.addEventListener('scroll', handleScroll, { passive: true });
+    document.addEventListener('scroll', handleScroll, { passive: true, capture: true });
+    return {
+        getExpanded: () => isExpanded,
+        setExpanded: applyExpandedState,
+        toggle,
+        dispose: () => {
+            toggleButton?.removeEventListener('click', toggle);
+            shell?.removeEventListener('scroll', handleScroll);
+            document.removeEventListener('scroll', handleScroll, true);
+        },
+    };
+}

package/dist/ui/shared/widget-state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Widget state persistence for MCP Apps hosts.
+ *
+ * ChatGPT has a special extension (window.openai.widgetState) for persisting
+ * widget state across page refreshes. Other hosts use the standard MCP Apps
+ * pattern where ui/notifications/tool-result is re-sent when needed.
+ *
+ * This module provides a simple abstraction:
+ * - ChatGPT: Uses window.openai.widgetState
+ * - Other hosts: No-op (rely on standard ui/notifications/tool-result)
+ */
+export interface WidgetStateStorage<T> {
+    /** Read persisted state, returns undefined if not found or not supported */
+    read(): T | undefined;
+    /** Persist state for recovery after refresh (no-op on unsupported hosts) */
+    write(state: T): void;
+}
+/**
+ * Check if we're running in ChatGPT (has special widget state API)
+ */
+export declare function isChatGPT(): boolean;
+/**
+ * Create a widget state storage adapter.
+ *
+ * On ChatGPT: Uses window.openai.widgetState for persistence
+ * On other hosts: Returns no-op adapter (state comes from ui/notifications/tool-result)
+ */
+export declare function createWidgetStateStorage<T>(validator?: (state: unknown) => boolean): WidgetStateStorage<T>;

package/dist/ui/shared/widget-state.js

@@ -0,0 +1,60 @@
+/**
+ * Widget state persistence for MCP Apps hosts.
+ *
+ * ChatGPT has a special extension (window.openai.widgetState) for persisting
+ * widget state across page refreshes. Other hosts use the standard MCP Apps
+ * pattern where ui/notifications/tool-result is re-sent when needed.
+ *
+ * This module provides a simple abstraction:
+ * - ChatGPT: Uses window.openai.widgetState
+ * - Other hosts: No-op (rely on standard ui/notifications/tool-result)
+ */
+/**
+ * Check if we're running in ChatGPT (has special widget state API)
+ */
+export function isChatGPT() {
+    return typeof window !== 'undefined' &&
+        typeof window.openai?.setWidgetState === 'function';
+}
+/**
+ * Create a widget state storage adapter.
+ *
+ * On ChatGPT: Uses window.openai.widgetState for persistence
+ * On other hosts: Returns no-op adapter (state comes from ui/notifications/tool-result)
+ */
+export function createWidgetStateStorage(validator) {
+    if (!isChatGPT()) {
+        // Other hosts don't have widget state persistence - return no-op
+        return {
+            read: () => undefined,
+            write: () => { }
+        };
+    }
+    // ChatGPT-specific implementation
+    return {
+        read() {
+            try {
+                const state = window.openai?.widgetState;
+                if (state === undefined || state === null)
+                    return undefined;
+                const payload = state.payload;
+                if (payload === undefined)
+                    return undefined;
+                if (validator && !validator(payload))
+                    return undefined;
+                return payload;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write(state) {
+            try {
+                window.openai?.setWidgetState?.({ payload: state });
+            }
+            catch {
+                // Ignore write failures
+            }
+        }
+    };
+}

package/dist/utils/capture.d.ts

@@ -15,6 +15,7 @@ export declare function sanitizeError(error: any): {
 export declare const captureBase: (captureURL: string, event: string, properties?: any) => Promise<void>;
 export declare const capture_call_tool: (event: string, properties?: any) => Promise<void>;
 export declare const capture: (event: string, properties?: any) => Promise<void>;
+export declare const capture_ui_event: (event: string, properties?: any) => Promise<void>;
 /**
  * Wrapper for capture() that automatically adds remote flag for remote-device telemetry
  * Also adds additional privacy filtering to remove sensitive identity information