@hcu-lab.me/mcp-device 1.0.0

package/dist/utils/feature-flags.js

@@ -0,0 +1,215 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { existsSync } from 'fs';
+import { CONFIG_FILE } from '../config.js';
+import { logger } from './logger.js';
+class FeatureFlagManager {
+    constructor() {
+        this.flags = {};
+        this.lastFetch = 0;
+        this.cacheMaxAge = 30 * 60 * 1000;
+        this.refreshInterval = null;
+        // Track fresh fetch status for A/B tests that need network flags
+        this.freshFetchPromise = null;
+        this.resolveFreshFetch = null;
+        this.loadedFromCache = false;
+        const configDir = path.dirname(CONFIG_FILE);
+        this.cachePath = path.join(configDir, 'feature-flags.json');
+        // Use production flags (v2 supports weighted variants)
+        this.flagUrl = process.env.DC_FLAG_URL ||
+            'https://desktopcommander.app/flags/v2/production.json';
+        // Set up promise for waiting on fresh fetch
+        this.freshFetchPromise = new Promise((resolve) => {
+            this.resolveFreshFetch = resolve;
+        });
+    }
+    /**
+     * Initialize - load from cache and start background refresh
+     */
+    async initialize() {
+        try {
+            // Load from cache immediately (non-blocking)
+            await this.loadFromCache();
+            // Fetch in background (don't block startup)
+            this.fetchFlags().then(() => {
+                // Signal that fresh flags are now available
+                if (this.resolveFreshFetch) {
+                    this.resolveFreshFetch();
+                }
+            }).catch(err => {
+                logger.debug('Initial flag fetch failed:', err.message);
+                // Still resolve the promise so waiters don't hang forever
+                if (this.resolveFreshFetch) {
+                    this.resolveFreshFetch();
+                }
+            });
+            // Start periodic refresh every 5 minutes
+            this.refreshInterval = setInterval(() => {
+                this.fetchFlags().catch(err => {
+                    logger.debug('Periodic flag fetch failed:', err.message);
+                });
+            }, this.cacheMaxAge);
+            // Allow process to exit even if interval is pending
+            // This is critical for proper cleanup when MCP client disconnects
+            this.refreshInterval.unref();
+            logger.info(`Feature flags initialized (refresh every ${this.cacheMaxAge / 1000}s)`);
+        }
+        catch (error) {
+            logger.warning('Failed to initialize feature flags:', error);
+        }
+    }
+    /**
+     * Get a flag value
+     */
+    get(flagName, defaultValue = false) {
+        return this.flags[flagName] !== undefined ? this.flags[flagName] : defaultValue;
+    }
+    /**
+     * Get all flags for debugging
+     */
+    getAll() {
+        return { ...this.flags };
+    }
+    /**
+     * Manually refresh flags immediately (for testing)
+     */
+    async refresh() {
+        try {
+            await this.fetchFlags();
+            return true;
+        }
+        catch (error) {
+            logger.error('Manual refresh failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Check if flags were loaded from cache (vs fresh fetch)
+     */
+    wasLoadedFromCache() {
+        return this.loadedFromCache;
+    }
+    /**
+     * Wait for fresh flags to be fetched from network.
+     * Use this when you need to ensure flags are loaded before making decisions
+     * (e.g., A/B test assignments for new users who don't have a cache yet)
+     *
+     * Has a hard timeout to prevent blocking MCP startup if the fetch hangs.
+     * See: https://github.com/wonderwhy-er/DesktopCommanderMCP/issues/465
+     */
+    async waitForFreshFlags() {
+        if (this.freshFetchPromise) {
+            let safetyTimeoutHandle;
+            try {
+                const safetyTimeout = new Promise((resolve) => {
+                    safetyTimeoutHandle = setTimeout(resolve, 5000);
+                });
+                await Promise.race([this.freshFetchPromise, safetyTimeout]);
+            }
+            finally {
+                if (safetyTimeoutHandle) {
+                    clearTimeout(safetyTimeoutHandle);
+                }
+            }
+        }
+    }
+    /**
+     * Load flags from local cache
+     */
+    async loadFromCache() {
+        try {
+            if (!existsSync(this.cachePath)) {
+                logger.debug('No feature flag cache found');
+                this.loadedFromCache = false;
+                return;
+            }
+            const data = await fs.readFile(this.cachePath, 'utf8');
+            const config = JSON.parse(data);
+            if (config.flags) {
+                this.flags = config.flags;
+                this.lastFetch = Date.now();
+                this.loadedFromCache = true;
+                logger.debug(`Loaded ${Object.keys(this.flags).length} feature flags from cache`);
+            }
+        }
+        catch (error) {
+            logger.warning('Failed to load feature flags from cache:', error);
+            this.loadedFromCache = false;
+        }
+    }
+    /**
+     * Fetch flags from remote URL
+     */
+    async fetchFlags() {
+        const FETCH_TIMEOUT_MS = 3000;
+        const controller = new AbortController();
+        const abortTimeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        let hardTimeoutHandle;
+        try {
+            // Don't log here - runs async and can interfere with MCP clients
+            // Use Promise.race as a hard timeout safety net.
+            // On some platforms (Windows + Node 24 / undici 7.x), AbortController.abort()
+            // fails to interrupt an in-progress TCP connect — the fetch hangs until the
+            // OS-level TCP timeout (~30s on Windows). Promise.race guarantees we reject
+            // at the JS level regardless of AbortController behavior.
+            // See: https://github.com/wonderwhy-er/DesktopCommanderMCP/issues/465
+            const fetchPromise = fetch(this.flagUrl, {
+                signal: controller.signal,
+                headers: {
+                    'Cache-Control': 'no-cache',
+                }
+            });
+            const hardTimeout = new Promise((_, reject) => hardTimeoutHandle = setTimeout(() => reject(new Error('Feature flags fetch timed out')), FETCH_TIMEOUT_MS));
+            const response = await Promise.race([fetchPromise, hardTimeout]);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const config = await response.json();
+            // Update flags
+            if (config.flags) {
+                this.flags = config.flags;
+                this.lastFetch = Date.now();
+                // Save to cache (silently - don't log during async operations
+                // as it can interfere with MCP clients that close quickly)
+                await this.saveToCache(config);
+            }
+        }
+        catch (error) {
+            logger.debug('Failed to fetch feature flags:', error.message);
+            // Continue with cached values
+        }
+        finally {
+            clearTimeout(abortTimeout);
+            if (hardTimeoutHandle) {
+                clearTimeout(hardTimeoutHandle);
+            }
+        }
+    }
+    /**
+     * Save flags to local cache
+     */
+    async saveToCache(config) {
+        try {
+            const configDir = path.dirname(this.cachePath);
+            if (!existsSync(configDir)) {
+                await fs.mkdir(configDir, { recursive: true });
+            }
+            await fs.writeFile(this.cachePath, JSON.stringify(config, null, 2), 'utf8');
+            // Don't log here - this runs async and can cause issues with MCP clients
+        }
+        catch (error) {
+            logger.warning('Failed to save feature flags to cache:', error);
+        }
+    }
+    /**
+     * Cleanup on shutdown
+     */
+    destroy() {
+        if (this.refreshInterval) {
+            clearInterval(this.refreshInterval);
+            this.refreshInterval = null;
+        }
+    }
+}
+// Export singleton instance
+export const featureFlagManager = new FeatureFlagManager();

package/dist/utils/files/base.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Base interfaces and types for file handling system
+ * All file handlers implement the FileHandler interface
+ */
+/**
+ * Base interface that all file handlers must implement
+ */
+export interface FileHandler {
+    /**
+     * Read file content
+     * @param path Validated file path
+     * @param options Read options (offset, length, sheet, etc.)
+     * @returns File result with content and metadata
+     */
+    read(path: string, options?: ReadOptions): Promise<FileResult>;
+    /**
+     * Write file (complete rewrite or append)
+     * @param path Validated file path
+     * @param content Content to write
+     * @param mode Write mode: 'rewrite' (default) or 'append'
+     */
+    write(path: string, content: any, mode?: 'rewrite' | 'append'): Promise<void>;
+    /**
+     * Edit a specific range (bulk rewrite)
+     * PRIMARY METHOD for structured file editing (Excel, etc.)
+     * Simpler and more powerful than location-based edits
+     * Supports:
+     * - Cell ranges: "Sheet1!A1:C10" with 2D array content
+     * - Whole sheets: "Sheet1" to replace entire sheet
+     * - Chunking: Update 1000 rows at a time for large files
+     *
+     * Currently implemented by: ExcelFileHandler
+     * TECHNICAL DEBT: TextFileHandler should also implement this for search/replace
+     * (logic currently in src/tools/edit.ts - see comments there)
+     *
+     * @param path Validated file path
+     * @param range Range identifier (e.g., "Sheet1!A1:C10" or "Sheet1")
+     * @param content New content for the range (2D array for Excel)
+     * @param options Additional format-specific options
+     * @returns Result with success status
+     */
+    editRange?(path: string, range: string, content: any, options?: Record<string, any>): Promise<EditResult>;
+    /**
+     * Get file metadata
+     * @param path Validated file path
+     * @returns File information including type-specific metadata
+     */
+    getInfo(path: string): Promise<FileInfo>;
+    /**
+     * Check if this handler can handle the given file
+     * @param path File path
+     * @returns true if this handler supports this file type (can be async for content-based checks)
+     */
+    canHandle(path: string): boolean | Promise<boolean>;
+}
+/**
+ * Options for reading files
+ */
+export interface ReadOptions {
+    /** Whether the path is a URL */
+    isUrl?: boolean;
+    /** Starting line/row number (for text/excel) */
+    offset?: number;
+    /** Maximum number of lines/rows to read */
+    length?: number;
+    /** Excel-specific: Sheet name or index */
+    sheet?: string | number;
+    /** Excel-specific: Cell range (e.g., "A1:C10") */
+    range?: string;
+    /** Whether to include status messages (default: true) */
+    includeStatusMessage?: boolean;
+    /** Optional AbortSignal to cancel an in-flight read (frees fd/thread on timeout). */
+    signal?: AbortSignal;
+}
+/**
+ * Result from reading a file
+ */
+export interface FileResult {
+    /** File content (string for text/csv, Buffer for binary, base64 string for images) */
+    content: string | Buffer;
+    /** MIME type of the content */
+    mimeType: string;
+    /** Type-specific metadata */
+    metadata?: FileMetadata;
+}
+/**
+ * File-type specific metadata
+ */
+export interface FileMetadata {
+    /** For images */
+    isImage?: boolean;
+    /** For directories (read_file fallback to listDirectory) */
+    isDirectory?: boolean;
+    /** For binary files */
+    isBinary?: boolean;
+    /** For Excel files */
+    isExcelFile?: boolean;
+    sheets?: ExcelSheet[];
+    fileSize?: number;
+    isLargeFile?: boolean;
+    /** For text files */
+    lineCount?: number;
+    /** For PDF files */
+    isPdf?: boolean;
+    author?: string;
+    title?: string;
+    totalPages?: number;
+    pages?: PdfPageItem[];
+    /** For DOCX files */
+    isDocx?: boolean;
+    /** Error information if operation failed */
+    error?: boolean;
+    errorMessage?: string;
+}
+/**
+ * PDF page content item
+ */
+export interface PdfPageItem {
+    pageNumber: number;
+    text: string;
+    images: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+}
+/**
+ * Excel sheet metadata
+ */
+export interface ExcelSheet {
+    /** Sheet name */
+    name: string;
+    /** Number of rows in sheet */
+    rowCount: number;
+    /** Number of columns in sheet */
+    colCount: number;
+}
+/**
+ * Result from edit operation (used by editRange)
+ */
+export interface EditResult {
+    /** Whether all edits succeeded */
+    success: boolean;
+    /** Number of edits successfully applied */
+    editsApplied: number;
+    /** Errors that occurred during editing */
+    errors?: Array<{
+        location: string;
+        error: string;
+    }>;
+}
+/**
+ * File information and metadata
+ */
+export interface FileInfo {
+    /** File size in bytes */
+    size: number;
+    /** Creation time */
+    created: Date;
+    /** Last modification time */
+    modified: Date;
+    /** Last access time */
+    accessed: Date;
+    /** Is this a directory */
+    isDirectory: boolean;
+    /** Is this a regular file */
+    isFile: boolean;
+    /** File permissions (octal string) */
+    permissions: string;
+    /** File type classification */
+    fileType: 'text' | 'excel' | 'image' | 'binary' | 'docx';
+    /** Type-specific metadata */
+    metadata?: FileMetadata;
+}

package/dist/utils/files/base.js

@@ -0,0 +1,5 @@
+/**
+ * Base interfaces and types for file handling system
+ * All file handlers implement the FileHandler interface
+ */
+export {};

package/dist/utils/files/binary.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Binary file handler
+ * Handles binary files that aren't supported by other handlers (Excel, Image)
+ * Uses isBinaryFile for content-based detection
+ * Returns instructions to use start_process with appropriate tools
+ */
+import { FileHandler, ReadOptions, FileResult, FileInfo } from './base.js';
+/**
+ * Binary file handler implementation
+ * Uses content-based detection via isBinaryFile
+ */
+export declare class BinaryFileHandler implements FileHandler {
+    canHandle(filePath: string): Promise<boolean>;
+    read(filePath: string, options?: ReadOptions): Promise<FileResult>;
+    write(path: string, content: any): Promise<void>;
+    getInfo(path: string): Promise<FileInfo>;
+    /**
+     * Generate instructions for handling binary files
+     */
+    private getBinaryInstructions;
+}

package/dist/utils/files/binary.js

@@ -0,0 +1,65 @@
+/**
+ * Binary file handler
+ * Handles binary files that aren't supported by other handlers (Excel, Image)
+ * Uses isBinaryFile for content-based detection
+ * Returns instructions to use start_process with appropriate tools
+ */
+import fs from "fs/promises";
+import path from "path";
+import { isBinaryFile } from 'isbinaryfile';
+/**
+ * Binary file handler implementation
+ * Uses content-based detection via isBinaryFile
+ */
+export class BinaryFileHandler {
+    async canHandle(filePath) {
+        // Content-based binary detection using isBinaryFile
+        try {
+            return await isBinaryFile(filePath);
+        }
+        catch (error) {
+            // If we can't check (file doesn't exist, etc.), don't handle it
+            return false;
+        }
+    }
+    async read(filePath, options) {
+        const instructions = this.getBinaryInstructions(filePath);
+        return {
+            content: instructions,
+            mimeType: 'text/plain',
+            metadata: {
+                isBinary: true
+            }
+        };
+    }
+    async write(path, content) {
+        throw new Error('Cannot write binary files directly. Use start_process with appropriate tools (Python, Node.js libraries, command-line utilities).');
+    }
+    async getInfo(path) {
+        const stats = await fs.stat(path);
+        return {
+            size: stats.size,
+            created: stats.birthtime,
+            modified: stats.mtime,
+            accessed: stats.atime,
+            isDirectory: stats.isDirectory(),
+            isFile: stats.isFile(),
+            permissions: stats.mode.toString(8).slice(-3),
+            fileType: 'binary',
+            metadata: {
+                isBinary: true
+            }
+        };
+    }
+    /**
+     * Generate instructions for handling binary files
+     */
+    getBinaryInstructions(filePath) {
+        const fileName = path.basename(filePath);
+        return `Cannot read binary file as text: ${fileName}
+
+Use start_process + interact_with_process to analyze binary files with appropriate tools (Node.js or Python libraries, command-line utilities, etc.).
+
+The read_file tool only handles text files, images, and Excel files.`;
+    }
+}

package/dist/utils/files/docx.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DOCX File Handler
+ *
+ * Approach: expose DOCX as filtered/raw XML through existing read_file + edit_block.
+ *
+ * READ (default): Returns a text-bearing outline — skips shapes, drawings, SVG noise.
+ *   Shows paragraphs with text, tables with cell content, style info, and image refs.
+ *   Each element shows its raw XML tag context so Claude can target it for editing.
+ *
+ * READ (with offset/length): Returns raw pretty-printed XML with line pagination,
+ *   so Claude can drill into specific sections when the outline isn't enough.
+ *
+ * EDIT (old_string/new_string): Find/replace on the pretty-printed XML, then
+ *   compact and repack into valid DOCX. Works exactly like text file editing.
+ *
+ * Round-trip: DOCX → unzip → pretty-print → [outline or raw] → edit → compact → repack
+ */
+import { FileHandler, FileResult, FileInfo, ReadOptions, EditResult } from './base.js';
+export declare class DocxFileHandler implements FileHandler {
+    private readonly extensions;
+    canHandle(path: string): boolean;
+    /**
+     * Read DOCX content.
+     *
+     * Default (offset=0, no explicit length or default length): returns outline
+     * With offset/length: returns raw pretty-printed XML with line pagination
+     */
+    read(path: string, options?: ReadOptions): Promise<FileResult>;
+    /**
+     * Write/create a DOCX file.
+     * Content is plain text — each line becomes a paragraph.
+     * Lines starting with # become headings (# = Heading1, ## = Heading2, etc.)
+     */
+    write(path: string, content: any, mode?: 'rewrite' | 'append'): Promise<void>;
+    /**
+     * Edit DOCX via find/replace on pretty-printed XML.
+     *
+     * Works on the same representation that read() returns when using offset/length,
+     * so XML fragments copied from read output work as search strings.
+     * After editing, XML is compacted and repacked into the DOCX.
+     */
+    editRange(path: string, _range: string, content: any, options?: Record<string, any>): Promise<EditResult>;
+    /**
+     * Get DOCX file info
+     */
+    getInfo(path: string): Promise<FileInfo>;
+}