@wonderwhy-er/desktop-commander 0.2.22 → 0.2.24

package/dist/server.js

@@ -8,7 +8,7 @@ const OS_GUIDANCE = getOSSpecificGuidance(SYSTEM_INFO);
 const DEV_TOOL_GUIDANCE = getDevelopmentToolGuidance(SYSTEM_INFO);
 const PATH_GUIDANCE = `IMPORTANT: ${getPathGuidance(SYSTEM_INFO)} Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.`;
 const CMD_PREFIX_DESCRIPTION = `This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.`;
-import { StartProcessArgsSchema, ReadProcessOutputArgsSchema, InteractWithProcessArgsSchema, ForceTerminateArgsSchema, ListSessionsArgsSchema, KillProcessArgsSchema, ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, CreateDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, GetConfigArgsSchema, SetConfigValueArgsSchema, ListProcessesArgsSchema, EditBlockArgsSchema, GetUsageStatsArgsSchema, GiveFeedbackArgsSchema, StartSearchArgsSchema, GetMoreSearchResultsArgsSchema, StopSearchArgsSchema, ListSearchesArgsSchema, GetPromptsArgsSchema, GetRecentToolCallsArgsSchema, } from './tools/schemas.js';
+import { StartProcessArgsSchema, ReadProcessOutputArgsSchema, InteractWithProcessArgsSchema, ForceTerminateArgsSchema, ListSessionsArgsSchema, KillProcessArgsSchema, ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, CreateDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, GetConfigArgsSchema, SetConfigValueArgsSchema, ListProcessesArgsSchema, EditBlockArgsSchema, GetUsageStatsArgsSchema, GiveFeedbackArgsSchema, StartSearchArgsSchema, GetMoreSearchResultsArgsSchema, StopSearchArgsSchema, ListSearchesArgsSchema, GetPromptsArgsSchema, GetRecentToolCallsArgsSchema, WritePdfArgsSchema, } from './tools/schemas.js';
 import { getConfig, setConfigValue } from './tools/config.js';
 import { getUsageStats } from './tools/usage.js';
 import { giveFeedbackToDesktopCommander } from './tools/feedback.js';
@@ -173,7 +173,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 name: "read_file",
                 description: `
-                        Read the contents of a file from the file system or a URL with optional offset and length parameters.
+                        Read contents from files and URLs.
+                        Read PDF files and extract content as markdown and images.
                         
                         Prefer this over 'execute_command' with cat/type for viewing files.
                         
@@ -200,9 +201,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         Can fetch content from URLs when isUrl parameter is set to true
                         (URLs are always read in full regardless of offset/length).
                         
-                        Handles text files normally and image files are returned as viewable images.
-                        Recognized image types: PNG, JPEG, GIF, WebP.
-                        
+                        FORMAT HANDLING (by extension):
+                        - Text: Uses offset/length for line-based pagination
+                        - Excel (.xlsx, .xls, .xlsm): Returns JSON 2D array
+                          * sheet: "Sheet1" (name) or "0" (index as string, 0-based)
+                          * range: ALWAYS use FROM:TO format (e.g., "A1:D100", "C1:C1", "B2:B50")
+                          * offset/length work as row pagination (optional fallback)
+                        - Images (PNG, JPEG, GIF, WebP): Base64 encoded viewable content
+                        - PDF: Extracts text content as markdown with page structure
+                          * offset/length work as page pagination (0-based)
+                          * Includes embedded images when available
+
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(ReadFileArgsSchema),
@@ -235,7 +244,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 name: "write_file",
                 description: `
-                        Write or append to file contents. 
+                        Write or append to file contents.
+
+                        IMPORTANT: DO NOT use this tool to create PDF files. Use 'write_pdf' for all PDF creation tasks.
 
                         CHUNKING IS STANDARD PRACTICE: Always write files in chunks of 25-30 lines maximum.
                         This is the normal, recommended way to write files - not an emergency measure.
@@ -251,16 +262,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         1. Any file expected to be longer than 25-30 lines
                         2. When writing multiple files in sequence
                         3. When creating documentation, code files, or configuration files
-                        
+
                         HANDLING CONTINUATION ("Continue" prompts):
                         If user asks to "Continue" after an incomplete operation:
                         1. Read the file to see what was successfully written
                         2. Continue writing ONLY the remaining content using {mode: 'append'}
                         3. Keep chunks to 25-30 lines each
-                        
+
+                        FORMAT HANDLING (by extension):
+                        - Text files: String content
+                        - Excel (.xlsx, .xls, .xlsm): JSON 2D array or {"SheetName": [[...]]}
+                          Example: '[["Name","Age"],["Alice",30]]'
+
                         Files over 50 lines will generate performance notes but are still written successfully.
                         Only works within allowed directories.
-                        
+
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(WriteFileArgsSchema),
@@ -271,6 +287,68 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     openWorldHint: false,
                 },
             },
+            {
+                name: "write_pdf",
+                description: `
+                        Create a new PDF file or modify an existing one.
+
+                        THIS IS THE ONLY TOOL FOR CREATING AND MODIFYING PDF FILES.
+
+                        RULES ABOUT FILENAMES:
+                        - When creating a new PDF, 'outputPath' MUST be provided and MUST use a new unique filename (e.g., "result_01.pdf", "analysis_2025_01.pdf", etc.).
+
+                        MODES:
+                        1. CREATE NEW PDF:
+                           - Pass a markdown string as 'content'.
+                           write_pdf(path="doc.pdf", content="# Title\\n\\nBody text...")
+
+                        2. MODIFY EXISTING PDF:
+                           - Pass array of operations as 'content'.
+                           - NEVER overwrite the original file.
+                           - ALWAYS provide a new filename in 'outputPath'.
+                           - After modifying, show original file path and new file path to user.
+
+                           write_pdf(path="doc.pdf", content=[
+                               { type: "delete", pageIndexes: [0, 2] },
+                               { type: "insert", pageIndex: 1, markdown: "# New Page" }
+                           ])
+
+                        OPERATIONS:
+                        - delete: Remove pages by 0-based index.
+                          { type: "delete", pageIndexes: [0, 1, 5] }
+
+                        - insert: Add pages at a specific 0-based index.
+                          { type: "insert", pageIndex: 0, markdown: "..." }
+                          { type: "insert", pageIndex: 5, sourcePdfPath: "/path/to/source.pdf" }
+
+                        PAGE BREAKS:
+                        To force a page break, use this HTML element:
+                        <div style="page-break-before: always;"></div>
+                        
+                        Example:
+                        "# Page 1\\n\\n<div style=\\"page-break-before: always;\\"></div>\\n\\n# Page 2"
+
+                        ADVANCED STYLING:
+                        HTML/CSS and inline SVG are supported for:
+                        - Text styling: colors, sizes, alignment, highlights
+                        - Boxes: borders, backgrounds, padding, rounded corners
+                        - SVG graphics: charts, diagrams, icons, shapes
+                        - Images: <img src="/absolute/path/image.jpg" width="300" /> or ![alt](/path/image.jpg)
+
+                        Supports standard markdown features including headers, lists, code blocks, tables, and basic formatting.
+
+                        Only works within allowed directories.
+
+                        ${PATH_GUIDANCE}
+                        ${CMD_PREFIX_DESCRIPTION}`,
+                inputSchema: zodToJsonSchema(WritePdfArgsSchema),
+                annotations: {
+                    title: "Write/Modify PDF",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    openWorldHint: false,
+                },
+            },
             {
                 name: "create_directory",
                 description: `
@@ -489,13 +567,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         Retrieve detailed metadata about a file or directory including:
                         - size
                         - creation time
-                        - last modified time 
+                        - last modified time
                         - permissions
                         - type
                         - lineCount (for text files)
                         - lastLine (zero-indexed number of last line, for text files)
                         - appendPosition (line number for appending, for text files)
-                        
+                        - sheets (for Excel files - array of {name, rowCount, colCount})
+
                         Only works within allowed directories.
                         
                         ${PATH_GUIDANCE}
@@ -507,45 +586,54 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
             },
             // Note: list_allowed_directories removed - use get_config to check allowedDirectories
-            // Text editing tools
+            // Editing tools
             {
                 name: "edit_block",
                 description: `
-                        Apply surgical text replacements to files.
-                        
+                        Apply surgical edits to files.
+
                         BEST PRACTICE: Make multiple small, focused edits rather than one large edit.
-                        Each edit_block call should change only what needs to be changed - include just enough 
+                        Each edit_block call should change only what needs to be changed - include just enough
                         context to uniquely identify the text being modified.
-                        
+
+                        FORMAT HANDLING (by extension):
+
+                        EXCEL FILES (.xlsx, .xls, .xlsm) - Range Update mode:
+                        Takes:
+                        - file_path: Path to the Excel file
+                        - range: ALWAYS use FROM:TO format - "SheetName!A1:C10" or "SheetName!C1:C1"
+                        - content: 2D array, e.g., [["H1","H2"],["R1","R2"]]
+
+                        TEXT FILES - Find/Replace mode:
                         Takes:
                         - file_path: Path to the file to edit
                         - old_string: Text to replace
                         - new_string: Replacement text
-                        - expected_replacements: Optional parameter for number of replacements
-                        
+                        - expected_replacements: Optional number of replacements (default: 1)
+
                         By default, replaces only ONE occurrence of the search text.
-                        To replace multiple occurrences, provide the expected_replacements parameter with
+                        To replace multiple occurrences, provide expected_replacements with
                         the exact number of matches expected.
-                        
+
                         UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal
                         amount of context necessary (typically 1-3 lines) before and after the change point,
                         with exact whitespace and indentation.
-                        
+
                         When editing multiple sections, make separate edit_block calls for each distinct change
                         rather than one large replacement.
-                        
+
                         When a close but non-exact match is found, a character-level diff is shown in the format:
                         common_prefix{-removed-}{+added+}common_suffix to help you identify what's different.
-                        
+
                         Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns
                         if the edited file exceeds this limit. If this happens, consider breaking your edits into
                         smaller, more focused changes.
-                        
+
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(EditBlockArgsSchema),
                 annotations: {
-                    title: "Edit Text Block",
+                    title: "Edit Block",
                     readOnlyHint: false,
                     destructiveHint: true,
                     openWorldHint: false,
@@ -574,7 +662,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         
                         COMMON FILE ANALYSIS PATTERNS:
                         • start_process("python3 -i") → Python REPL for data analysis (RECOMMENDED)
-                        • start_process("node -i") → Node.js for JSON processing  
+                        • start_process("node -i") → Node.js REPL for JSON processing
+                        • start_process("node:local") → Node.js on MCP server (stateless, ES imports, all code in one call)
                         • start_process("cut -d',' -f1 file.csv | sort | uniq -c") → Quick CSV analysis
                         • start_process("wc -l /path/file.csv") → Line counting
                         • start_process("head -10 /path/file.csv") → File preview
@@ -583,12 +672,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         For PDF, Excel, Word, archives, databases, and other binary formats, use process tools with appropriate libraries or command-line utilities.
                         
                         INTERACTIVE PROCESSES FOR DATA ANALYSIS:
-                        1. start_process("python3 -i") - Start Python REPL for data work
-                        2. start_process("node -i") - Start Node.js REPL for JSON/JS
-                        3. start_process("bash") - Start interactive bash shell
+                        For code/calculations, use in this priority order:
+                        1. start_process("python3 -i") - Python REPL (preferred)
+                        2. start_process("node -i") - Node.js REPL (when Python unavailable)
+                        3. start_process("node:local") - Node.js fallback (when node -i fails)
                         4. Use interact_with_process() to send commands
                         5. Use read_process_output() to get responses
-                        
+                        When Python is unavailable, prefer Node.js over shell for calculations.
+                        Node.js: Always use ES import syntax (import x from 'y'), not require().
+
                         SMART DETECTION:
                         - Detects REPL prompts (>>>, >, $, etc.)
                         - Identifies when process is waiting for input
@@ -624,35 +716,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             {
                 name: "read_process_output",
                 description: `
-                        Read output from a running process with intelligent completion detection.
+                        Read output from a running process with file-like pagination support.
                         
-                        Automatically detects when process is ready for more input instead of timing out.
+                        Supports partial output reading with offset and length parameters (like read_file):
+                        - 'offset' (start line, default: 0)
+                          * offset=0: Read NEW output since last read (default, like old behavior)
+                          * Positive: Read from absolute line position
+                          * Negative: Read last N lines from end (tail behavior)
+                        - 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting)
                         
-                        SMART FEATURES:
-                        - Early exit when REPL shows prompt (>>>, >, etc.)
-                        - Detects process completion vs still running
-                        - Prevents hanging on interactive prompts
-                        - Clear status messages about process state
+                        Examples:
+                        - offset: 0, length: 100     → First 100 NEW lines since last read
+                        - offset: 0                  → All new lines (respects config limit)
+                        - offset: 500, length: 50    → Lines 500-549 (absolute position)
+                        - offset: -20                → Last 20 lines (tail)
+                        - offset: -50, length: 10    → Start 50 from end, read 10 lines
                         
-                        REPL USAGE:
-                        - Stops immediately when REPL prompt detected
-                        - Shows clear status: waiting for input vs finished
-                        - Shorter timeouts needed due to smart detection
-                        - Works with Python, Node.js, R, Julia, etc.
+                        OUTPUT PROTECTION:
+                        - Uses same fileReadLineLimit as read_file (default: 1000 lines)
+                        - Returns status like: [Reading 100 lines from line 0 (total: 5000 lines, 4900 remaining)]
+                        - Prevents context overflow from verbose processes
+                        
+                        SMART FEATURES:
+                        - For offset=0, waits up to timeout_ms for new output to arrive
+                        - Detects REPL prompts and process completion
+                        - Shows process state (waiting for input, finished, etc.)
                         
                         DETECTION STATES:
                         Process waiting for input (ready for interact_with_process)
                         Process finished execution
                         Timeout reached (may still be running)
 
-                        PERFORMANCE DEBUGGING (verbose_timing parameter):
-                        Set verbose_timing: true to get detailed timing information including:
-                        - Exit reason (early_exit_quick_pattern, early_exit_periodic_check, process_finished, timeout)
-                        - Total duration and time to first output
-                        - Complete timeline of all output events with timestamps
-                        - Which detection mechanism triggered early exit
-                        Use this to identify when timeouts could be reduced or detection patterns improved.
-
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(ReadProcessOutputArgsSchema),
                 annotations: {
@@ -692,7 +786,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         
                         SUPPORTED REPLs:
                         - Python: python3 -i (RECOMMENDED for data analysis)
-                        - Node.js: node -i  
+                        - Node.js: node -i
                         - R: R
                         - Julia: julia
                         - Shell: bash, zsh
@@ -781,9 +875,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 name: "kill_process",
                 description: `
                         Terminate a running process by PID.
-                        
+
                         Use with caution as this will forcefully terminate the specified process.
-                        
+
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(KillProcessArgsSchema),
                 annotations: {
@@ -881,27 +975,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         
                         USAGE:
                         When user says "1", "2", "3", "4", or "5" from onboarding:
-                        - "1" → get_prompts(action='get_prompt', promptId='onb2_01', anonymous_user_use_case='...')
-                        - "2" → get_prompts(action='get_prompt', promptId='onb2_02', anonymous_user_use_case='...')
-                        - "3" → get_prompts(action='get_prompt', promptId='onb2_03', anonymous_user_use_case='...')
-                        - "4" → get_prompts(action='get_prompt', promptId='onb2_04', anonymous_user_use_case='...')
-                        - "5" → get_prompts(action='get_prompt', promptId='onb2_05', anonymous_user_use_case='...')
-                        
-                        ANONYMOUS USE CASE (REQUIRED):
-                        Infer what GOAL or PROBLEM the user is trying to solve from conversation history.
-                        Focus on the job-to-be-done, not just what they were doing.
-                        
-                        GOOD (problem/goal focused):
-                        "automating backup workflow", "converting PDFs to CSV", "debugging test failures",
-                        "organizing project files", "monitoring server logs", "extracting data from documents"
-                        
-                        BAD (too vague or contains PII):
-                        "using Desktop Commander", "working on John's project", "fixing acme-corp bug"
-                        
-                        If unclear from context, use: "exploring tool capabilities"
+                        - "1" → get_prompts(action='get_prompt', promptId='onb2_01')
+                        - "2" → get_prompts(action='get_prompt', promptId='onb2_02')
+                        - "3" → get_prompts(action='get_prompt', promptId='onb2_03')
+                        - "4" → get_prompts(action='get_prompt', promptId='onb2_04')
+                        - "5" → get_prompts(action='get_prompt', promptId='onb2_05')
                         
                         The prompt content will be injected and execution begins immediately.
-                        
+
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(GetPromptsArgsSchema),
             }
@@ -940,6 +1021,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
         }
         capture_call_tool('server_call_tool', telemetryData);
+        // Log every tool request name
+        // logger.info(`Tool request: ${name}`, { toolName: name, timestamp: new Date().toISOString() });
         // Track tool call
         trackToolCall(name, args);
         // Using a more structured approach with dedicated handlers
@@ -1000,44 +1083,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                         prompt_title: prompt.title,
                                         category: prompt.categories[0] || 'uncategorized',
                                         author: prompt.author,
-                                        verified: prompt.verified
+                                        verified: prompt.verified,
+                                        // Temporarily disabled for privacy review - Dec 2025
+                                        // anonymous_use_case: (args as any).anonymous_user_use_case || null
                                     });
                                 }
                             }
-                            else if (action === 'list_categories') {
-                                // New analytics for category browsing
-                                const { loadPromptsData } = await import('./tools/prompts.js');
-                                const promptsData = await loadPromptsData();
-                                // Extract unique categories and count prompts in each
-                                const categoryMap = new Map();
-                                promptsData.prompts.forEach(prompt => {
-                                    prompt.categories.forEach(category => {
-                                        categoryMap.set(category, (categoryMap.get(category) || 0) + 1);
-                                    });
-                                });
-                                await capture('server_list_prompt_categories', {
-                                    total_categories: categoryMap.size,
-                                    total_prompts: promptsData.prompts.length,
-                                    categories_available: Array.from(categoryMap.keys())
-                                });
-                            }
-                            else if (action === 'list_prompts') {
-                                // New analytics for prompt list browsing
-                                const { loadPromptsData } = await import('./tools/prompts.js');
-                                const promptsData = await loadPromptsData();
-                                const category = args.category;
-                                let filteredPrompts = promptsData.prompts;
-                                if (category) {
-                                    filteredPrompts = promptsData.prompts.filter(prompt => prompt.categories.includes(category));
-                                }
-                                await capture('server_list_category_prompts', {
-                                    category_filter: category || 'all',
-                                    has_category_filter: !!category,
-                                    prompts_shown: filteredPrompts.length,
-                                    total_prompts_available: promptsData.prompts.length,
-                                    prompt_ids_shown: filteredPrompts.map(p => p.id)
-                                });
-                            }
                         }
                         catch (error) {
                             // Don't fail the request if analytics fail
@@ -1116,6 +1167,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "write_file":
                 result = await handlers.handleWriteFile(args);
                 break;
+            case "write_pdf":
+                result = await handlers.handleWritePdf(args);
+                break;
             case "create_directory":
                 result = await handlers.handleCreateDirectory(args);
                 break;

package/dist/terminal-manager.d.ts

@@ -1,11 +1,21 @@
 import { TerminalSession, CommandExecutionResult, ActiveSession } from './types.js';
 interface CompletedSession {
     pid: number;
-    output: string;
+    outputLines: string[];
     exitCode: number | null;
     startTime: Date;
     endTime: Date;
 }
+export interface PaginatedOutputResult {
+    lines: string[];
+    totalLines: number;
+    readFrom: number;
+    readCount: number;
+    remaining: number;
+    isComplete: boolean;
+    exitCode?: number | null;
+    runtimeMs?: number;
+}
 export declare class TerminalManager {
     private sessions;
     private completedSessions;
@@ -17,7 +27,51 @@ export declare class TerminalManager {
      */
     sendInputToProcess(pid: number, input: string): boolean;
     executeCommand(command: string, timeoutMs?: number, shell?: string, collectTiming?: boolean): Promise<CommandExecutionResult>;
-    getNewOutput(pid: number): string | null;
+    /**
+     * Append text to a session's line buffer
+     * Handles partial lines and newline splitting
+     */
+    private appendToLineBuffer;
+    /**
+     * Read process output with pagination (like file reading)
+     * @param pid Process ID
+     * @param offset Line offset: 0=from lastReadIndex, positive=absolute, negative=tail
+     * @param length Max lines to return
+     * @param updateReadIndex Whether to update lastReadIndex (default: true for offset=0)
+     */
+    readOutputPaginated(pid: number, offset?: number, length?: number): PaginatedOutputResult | null;
+    /**
+     * Internal helper to read from a line buffer with offset/length
+     */
+    private readFromLineBuffer;
+    /**
+     * Get total line count for a process
+     */
+    getOutputLineCount(pid: number): number | null;
+    /**
+     * Legacy method for backward compatibility
+     * Returns all new output since last read
+     * @param maxLines Maximum lines to return (default: 1000 for context protection)
+     * @deprecated Use readOutputPaginated instead
+     */
+    getNewOutput(pid: number, maxLines?: number): string | null;
+    /**
+     * Capture a snapshot of current output state for interaction tracking.
+     * Used by interactWithProcess to know what output existed before sending input.
+     */
+    captureOutputSnapshot(pid: number): {
+        totalChars: number;
+        lineCount: number;
+    } | null;
+    /**
+     * Get output that appeared since a snapshot was taken.
+     * This handles the case where output is appended to the last line (REPL prompts).
+     * Also checks completed sessions in case process finished between snapshot and poll.
+     */
+    getOutputSinceSnapshot(pid: number, snapshot: {
+        totalChars: number;
+        lineCount: number;
+    }): string | null;
     /**
    * Get a session by PID
    * @param pid Process ID