@wonderwhy-er/desktop-commander 0.2.42 → 0.2.44

package/dist/utils/files/text.js

@@ -43,7 +43,7 @@ export class TextFileHandler {
         const length = options?.length ?? 1000; // Default from config
         const includeStatusMessage = options?.includeStatusMessage ?? true;
         // Binary detection is done at factory level - just read as text
-        return this.readFileWithSmartPositioning(filePath, offset, length, 'text/plain', includeStatusMessage);
+        return this.readFileWithSmartPositioning(filePath, offset, length, 'text/plain', includeStatusMessage, options?.signal);
     }
     async write(path, content, mode = 'rewrite') {
         if (mode === 'append') {
@@ -100,11 +100,11 @@ export class TextFileHandler {
     /**
      * Get file line count (for files under size limit)
      */
-    async getFileLineCount(filePath) {
+    async getFileLineCount(filePath, signal) {
         try {
             const stats = await fs.stat(filePath);
             if (stats.size < FILE_SIZE_LIMITS.LINE_COUNT_LIMIT) {
-                const content = await fs.readFile(filePath, 'utf8');
+                const content = await fs.readFile(filePath, { encoding: 'utf8', signal });
                 return TextFileHandler.countLines(content);
             }
         }
@@ -179,32 +179,32 @@ export class TextFileHandler {
     /**
      * Read file with smart positioning for optimal performance
      */
-    async readFileWithSmartPositioning(filePath, offset, length, mimeType, includeStatusMessage = true) {
+    async readFileWithSmartPositioning(filePath, offset, length, mimeType, includeStatusMessage = true, signal) {
         const stats = await fs.stat(filePath);
         const fileSize = stats.size;
-        const totalLines = await this.getFileLineCount(filePath);
+        const totalLines = await this.getFileLineCount(filePath, signal);
         // For negative offsets (tail behavior), use reverse reading
         if (offset < 0) {
             const requestedLines = Math.abs(offset);
             if (fileSize > FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD &&
                 requestedLines <= READ_PERFORMANCE_THRESHOLDS.SMALL_READ_THRESHOLD) {
-                return await this.readLastNLinesReverse(filePath, requestedLines, mimeType, includeStatusMessage, totalLines);
+                return await this.readLastNLinesReverse(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
             }
             else {
-                return await this.readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage, totalLines);
+                return await this.readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
             }
         }
         // For positive offsets
         else {
             if (fileSize < FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD || offset === 0) {
-                return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
             }
             else {
                 if (offset > READ_PERFORMANCE_THRESHOLDS.DEEP_OFFSET_THRESHOLD) {
-                    return await this.readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                    return await this.readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
                 }
                 else {
-                    return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines);
+                    return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
                 }
             }
         }
@@ -212,7 +212,7 @@ export class TextFileHandler {
     /**
      * Read last N lines efficiently by reading file backwards
      */
-    async readLastNLinesReverse(filePath, n, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readLastNLinesReverse(filePath, n, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const fd = await fs.open(filePath, 'r');
         try {
             const stats = await fd.stat();
@@ -221,6 +221,11 @@ export class TextFileHandler {
             let lines = [];
             let partialLine = '';
             while (position > 0 && lines.length < n) {
+                if (signal?.aborted) {
+                    const err = new Error('Read aborted');
+                    err.code = 'ABORT_ERR';
+                    throw err;
+                }
                 const readSize = Math.min(READ_PERFORMANCE_THRESHOLDS.CHUNK_SIZE, position);
                 position -= readSize;
                 const buffer = Buffer.alloc(readSize);
@@ -247,9 +252,9 @@ export class TextFileHandler {
     /**
      * Read from end using readline with circular buffer
      */
-    async readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         const buffer = new Array(requestedLines);
@@ -279,9 +284,9 @@ export class TextFileHandler {
     /**
      * Read from start/middle using readline
      */
-    async readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         const result = [];
@@ -308,10 +313,10 @@ export class TextFileHandler {
     /**
      * Read from estimated byte position for very large files
      */
-    async readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines) {
+    async readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
         // First, do a quick scan to estimate lines per byte
         const rl = createInterface({
-            input: createReadStream(filePath),
+            input: createReadStream(filePath, { signal }),
             crlfDelay: Infinity
         });
         let sampleLines = 0;
@@ -324,7 +329,7 @@ export class TextFileHandler {
         }
         rl.close();
         if (sampleLines === 0) {
-            return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, fileTotalLines);
+            return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, fileTotalLines, signal);
         }
         // Estimate position
         const avgLineLength = bytesRead / sampleLines;
@@ -333,7 +338,7 @@ export class TextFileHandler {
         try {
             const stats = await fd.stat();
             const startPosition = Math.min(estimatedBytePosition, stats.size);
-            const stream = createReadStream(filePath, { start: startPosition });
+            const stream = createReadStream(filePath, { start: startPosition, signal });
             const rl2 = createInterface({
                 input: stream,
                 crlfDelay: Infinity

package/dist/utils/open-browser.d.ts

@@ -6,4 +6,4 @@ export declare function openBrowser(url: string): Promise<void>;
 /**
  * Open the Desktop Commander welcome page
  */
-export declare function openWelcomePage(): Promise<void>;
+export declare function openWelcomePage(clientName?: string): Promise<void>;

package/dist/utils/open-browser.js

@@ -37,7 +37,10 @@ export async function openBrowser(url) {
 /**
  * Open the Desktop Commander welcome page
  */
-export async function openWelcomePage() {
-    const url = 'https://desktopcommander.app/welcome/';
+export async function openWelcomePage(clientName) {
+    // utm_source is auto-captured by the welcome page's PostHog (and GA4), so
+    // web analytics can segment by MCP client without any web-side changes.
+    const url = 'https://desktopcommander.app/welcome/'
+        + (clientName ? `?utm_source=${encodeURIComponent(clientName)}` : '');
     await openBrowser(url);
 }

package/dist/utils/unsupportedParams.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility for detecting parameters a caller sent that a tool's Zod schema does
+ * not accept.
+ *
+ * Zod's default `z.object()` silently strips unknown keys, so a model that
+ * invents a parameter (e.g. `view_range`) gets a normal-looking response with no
+ * signal that its input was ignored. These helpers let the dispatcher surface a
+ * corrective warning instead.
+ *
+ * Detection is top-level only. That is sufficient here because none of the tool
+ * arg schemas use a top-level `.passthrough()`/catchall — free-form fields
+ * (`options`, `params`, `pdfOptions`) are named keys whose contents are
+ * intentionally unvalidated.
+ */
+/** List the parameter names a tool schema accepts (empty array if it takes none). */
+export declare function getSupportedParams(schema: unknown): string[];
+/**
+ * Return the names of top-level keys in `args` that the schema does not accept.
+ * Returns [] when args is not a plain object or the schema's params can't be
+ * determined (so we never warn on something we can't reason about).
+ */
+export declare function detectUnsupportedParams(args: unknown, schema: unknown): string[];
+/** Build the corrective warning string shown to the model. */
+export declare function buildUnsupportedParamsWarning(toolName: string, unsupported: string[], supported: string[]): string;

package/dist/utils/unsupportedParams.js

@@ -0,0 +1,66 @@
+/**
+ * Utility for detecting parameters a caller sent that a tool's Zod schema does
+ * not accept.
+ *
+ * Zod's default `z.object()` silently strips unknown keys, so a model that
+ * invents a parameter (e.g. `view_range`) gets a normal-looking response with no
+ * signal that its input was ignored. These helpers let the dispatcher surface a
+ * corrective warning instead.
+ *
+ * Detection is top-level only. That is sufficient here because none of the tool
+ * arg schemas use a top-level `.passthrough()`/catchall — free-form fields
+ * (`options`, `params`, `pdfOptions`) are named keys whose contents are
+ * intentionally unvalidated.
+ */
+/**
+ * Resolve a Zod schema down to the field map of its underlying object schema,
+ * unwrapping wrappers (effects/optional/default/nullable/branded) defensively.
+ * Returns null when the schema is not (and does not wrap) a plain object schema,
+ * in which case we cannot determine the supported parameters and must not warn.
+ */
+function getObjectShape(schema) {
+    let current = schema;
+    for (let i = 0; current && current._def && i < 10; i++) {
+        const typeName = current._def.typeName;
+        if (typeName === 'ZodObject') {
+            const shape = typeof current.shape === 'function' ? current.shape() : current.shape;
+            return shape ?? null;
+        }
+        if (typeName === 'ZodEffects')
+            current = current._def.schema;
+        else if (typeName === 'ZodOptional' || typeName === 'ZodNullable' || typeName === 'ZodDefault') {
+            current = typeof current._def.innerType === 'function' ? current._def.innerType() : current._def.innerType;
+        }
+        else if (typeName === 'ZodBranded')
+            current = current._def.type;
+        else
+            return null;
+    }
+    return null;
+}
+/** List the parameter names a tool schema accepts (empty array if it takes none). */
+export function getSupportedParams(schema) {
+    const shape = getObjectShape(schema);
+    return shape ? Object.keys(shape) : [];
+}
+/**
+ * Return the names of top-level keys in `args` that the schema does not accept.
+ * Returns [] when args is not a plain object or the schema's params can't be
+ * determined (so we never warn on something we can't reason about).
+ */
+export function detectUnsupportedParams(args, schema) {
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return [];
+    const shape = getObjectShape(schema);
+    if (shape === null)
+        return [];
+    const supported = new Set(Object.keys(shape));
+    return Object.keys(args).filter((k) => !supported.has(k));
+}
+/** Build the corrective warning string shown to the model. */
+export function buildUnsupportedParamsWarning(toolName, unsupported, supported) {
+    const ignored = unsupported.join(', ');
+    const supportedList = supported.length > 0 ? supported.join(', ') : '(none)';
+    return `You sent parameters not supported by this tool, which were ignored: ${ignored}. `
+        + `Supported parameters for ${toolName}: ${supportedList}.`;
+}

package/dist/utils/usageTracker.d.ts

@@ -38,7 +38,11 @@ declare class UsageTracker {
      */
     getStats(): Promise<ToolUsageStats>;
     /**
-     * Save usage stats to config
+     * Save usage stats to config.
+     * Non-blocking: the tool-call return path must not wait on a disk write. The
+     * in-memory stats are already updated by the caller (getStats returns the live
+     * config object), so persistence is coalesced in the background. This is what
+     * keeps a saturated libuv threadpool from gating tool responses on every call.
      */
     private saveStats;
     /**

package/dist/utils/usageTracker.js

@@ -45,10 +45,14 @@ class UsageTracker {
         return stats || this.getDefaultStats();
     }
     /**
-     * Save usage stats to config
+     * Save usage stats to config.
+     * Non-blocking: the tool-call return path must not wait on a disk write. The
+     * in-memory stats are already updated by the caller (getStats returns the live
+     * config object), so persistence is coalesced in the background. This is what
+     * keeps a saturated libuv threadpool from gating tool responses on every call.
      */
     async saveStats(stats) {
-        await configManager.setValue('usageStats', stats);
+        await configManager.setValueNonBlocking('usageStats', stats);
     }
     /**
      * Determine which category a tool belongs to
@@ -327,7 +331,14 @@ class UsageTracker {
     async shouldShowOnboarding() {
         // Check feature flag first (remote kill switch)
         const { featureFlagManager } = await import('./feature-flags.js');
-        const onboardingEnabled = featureFlagManager.get('onboarding_injection', true);
+        // Default false: on cold starts (no flag cache yet, e.g. ephemeral Docker
+        // containers) this can run before the background flag fetch completes.
+        // Treat an unknown flag as "off" so nothing is injected — flags load
+        // within seconds, so when the flag is ON onboarding still fires on a
+        // later call while the user is new. Deliberately no waiting here to keep
+        // tool calls latency-free.
+        // See: https://github.com/wonderwhy-er/DesktopCommanderMCP/issues/538
+        const onboardingEnabled = featureFlagManager.get('onboarding_injection', false);
         if (!onboardingEnabled) {
             return false;
         }

package/dist/utils/welcome-onboarding.d.ts

@@ -6,4 +6,4 @@
  * 2. Users in the 'showOnboardingPage' A/B variant
  * 3. Haven't seen it yet
  */
-export declare function handleWelcomePageOnboarding(): Promise<void>;
+export declare function handleWelcomePageOnboarding(clientName?: string): Promise<void>;

package/dist/utils/welcome-onboarding.js

@@ -12,7 +12,7 @@ import { capture } from './capture.js';
  * 2. Users in the 'showOnboardingPage' A/B variant
  * 3. Haven't seen it yet
  */
-export async function handleWelcomePageOnboarding() {
+export async function handleWelcomePageOnboarding(clientName) {
     // Check if this is a new install pending A/B decision
     // This flag is set when config is first created and survives process restarts
     const pending = await configManager.getValue('pendingWelcomeOnboarding');
@@ -48,7 +48,7 @@ export async function handleWelcomePageOnboarding() {
         return;
     }
     try {
-        await openWelcomePage();
+        await openWelcomePage(clientName);
         await configManager.setValue('sawOnboardingPage', true);
         await configManager.setValue('pendingWelcomeOnboarding', false);
         capture('server_welcome_page_opened', { success: true });

package/dist/utils/withTimeout.d.ts

@@ -9,3 +9,20 @@
  * @returns Promise that resolves with the operation result or the default value on timeout
  */
 export declare function withTimeout<T>(operation: Promise<T>, timeoutMs: number, operationName: string, defaultValue: T): Promise<T>;
+/**
+ * Run an operation under a timeout WITH real cancellation.
+ *
+ * Unlike withTimeout (which only races a timer and leaves the underlying work
+ * running — holding its libuv thread/fd until the OS call returns), this passes
+ * an AbortSignal into the operation and aborts it when the timeout fires, so a
+ * read/stream that honors the signal is cancelled and its resources released.
+ *
+ * Rejects with an Error whose `.code` is 'ETIMEDOUT' on timeout (so existing
+ * ETIMEDOUT handling / permission-error mapping keeps working).
+ *
+ * Caveat: an operation wedged inside a single un-interruptible syscall only
+ * observes the abort once that syscall returns; library reads that ignore the
+ * signal (e.g. Excel/PDF parsers) still get the timeout rejection but keep
+ * running in the background until they finish on their own.
+ */
+export declare function runWithAbortableTimeout<T>(operation: (signal: AbortSignal) => Promise<T>, timeoutMs: number, operationName: string): Promise<T>;

package/dist/utils/withTimeout.js

@@ -50,3 +50,36 @@ export function withTimeout(operation, timeoutMs, operationName, defaultValue) {
         });
     });
 }
+/**
+ * Run an operation under a timeout WITH real cancellation.
+ *
+ * Unlike withTimeout (which only races a timer and leaves the underlying work
+ * running — holding its libuv thread/fd until the OS call returns), this passes
+ * an AbortSignal into the operation and aborts it when the timeout fires, so a
+ * read/stream that honors the signal is cancelled and its resources released.
+ *
+ * Rejects with an Error whose `.code` is 'ETIMEDOUT' on timeout (so existing
+ * ETIMEDOUT handling / permission-error mapping keeps working).
+ *
+ * Caveat: an operation wedged inside a single un-interruptible syscall only
+ * observes the abort once that syscall returns; library reads that ignore the
+ * signal (e.g. Excel/PDF parsers) still get the timeout rejection but keep
+ * running in the background until they finish on their own.
+ */
+export function runWithAbortableTimeout(operation, timeoutMs, operationName) {
+    const controller = new AbortController();
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            controller.abort();
+            const error = new Error(`${operationName} timed out after ${timeoutMs / 1000} seconds`);
+            error.code = 'ETIMEDOUT';
+            reject(error);
+        }, timeoutMs);
+    });
+    const op = operation(controller.signal);
+    // Swallow the late abort rejection so it can't surface as an unhandled
+    // rejection after the timeout has already settled the race.
+    op.catch(() => { });
+    return Promise.race([op, timeout]).finally(() => clearTimeout(timeoutId));
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.42";
+export declare const VERSION = "0.2.44";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.2.42';
+export const VERSION = '0.2.44';

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@wonderwhy-er/desktop-commander",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "description": "MCP server for terminal operations and file editing",
   "mcpName": "io.github.wonderwhy-er/desktop-commander",
   "license": "MIT",
   "author": "Eduards Ruzga",
   "homepage": "https://github.com/wonderwhy-er/DesktopCommanderMCP",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP.git"
+  },
   "bugs": "https://github.com/wonderwhy-er/DesktopCommanderMCP/issues",
   "type": "module",
   "engines": {