@wonderwhy-er/desktop-commander 0.2.40 → 0.2.42

package/dist/utils/capture.js

@@ -1,7 +1,7 @@
 import { platform } from 'os';
 import * as https from 'https';
 import { configManager, isTelemetryDisabledValue } from '../config-manager.js';
-import { currentClient } from '../server.js';
+import { currentClient, currentCallIsRemote } from '../server.js';
 let VERSION = 'unknown';
 try {
     const versionModule = await import('../version.js');
@@ -13,8 +13,26 @@ catch {
 // Will be initialized when needed
 let uniqueUserId = 'unknown';
 // --- Telemetry Proxy (direct BigQuery ingestion) ---
-const TELEMETRY_PROXY_URL = 'https://dc-telemetry-proxy-83847352264.europe-west1.run.app/mp/collect';
-const TELEMETRY_PROXY_TOKEN = 'Od44UB_fTrVfGPGRPLr5QdVgFhuKdiGaBmvazTdxVdQ';
+// TODO: Move proxy endpoints, auth header setup, request retry/fallback, and
+// transport code into a dedicated telemetry utility once this migration lands.
+// TODO(security): bearer token was removed, so this endpoint is now unauthenticated.
+// Confirm the proxy enforces rate limiting / payload validation server-side,
+// otherwise anyone can POST arbitrary events straight into BigQuery ingestion.
+const TELEMETRY_PROXY_URL = 'https://telemetry.desktopcommander.app/mp/collect';
+const TELEMETRY_PROXY_FALLBACK_URL = 'https://dc-telemetry-proxy-83847352264.europe-west1.run.app/mp/collect';
+/**
+ * Hard kill-switch for telemetry via environment variable.
+ *
+ * Independent of the persisted `telemetryEnabled` config so that tests, CI and
+ * one-off runs can suppress all analytics without mutating the user's config.
+ * Set DESKTOP_COMMANDER_DISABLE_TELEMETRY to 1/true/yes/on to disable.
+ */
+export function isTelemetryDisabledByEnv() {
+    const raw = process.env.DESKTOP_COMMANDER_DISABLE_TELEMETRY;
+    if (!raw)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+}
 /**
  * Sanitizes error objects to remove potentially sensitive information like file paths
  * @param error Error object or string to sanitize
@@ -47,12 +65,19 @@ export function sanitizeError(error) {
     };
 }
 /**
- * Send an event to Google Analytics
+ * Send an event to telemetry
  * @param event Event name
  * @param properties Optional event properties
  */
+// TODO(cleanup): captureBase is now dead code — no caller remains after the GA
+// removal (only referenced in a comment). It still carries the full GA4-flavored
+// send path. Remove it, or repurpose it as the shared proxy transport.
 export const captureBase = async (captureURL, event, properties) => {
     try {
+        // Env kill-switch takes precedence over config (tests/CI).
+        if (isTelemetryDisabledByEnv()) {
+            return;
+        }
         // Check if telemetry is enabled in config (defaults to true if not set)
         const telemetryEnabled = await configManager.getValue('telemetryEnabled');
         // If telemetry is explicitly disabled or GA credentials are missing, don't send
@@ -178,9 +203,13 @@ export const captureBase = async (captureURL, event, properties) => {
         const eventProperties = {
             ...baseProperties,
             ...clientContext,
+            // Attribute events to the remote path when the in-flight tool call
+            // came from a remote device. Placed before sanitizedProperties so an
+            // explicit `remote` passed by the caller (e.g. captureRemote) wins.
+            ...(currentCallIsRemote ? { remote: String(true) } : {}),
             ...sanitizedProperties
         };
-        // Prepare GA4 payload
+        // Prepare telemetry payload
         const payload = {
             client_id: uniqueUserId,
             non_personalized_ads: false,
@@ -190,7 +219,7 @@ export const captureBase = async (captureURL, event, properties) => {
                     params: eventProperties
                 }]
         };
-        // Send data to Google Analytics
+        // Send data to telemetry endpoint
         const postData = JSON.stringify(payload);
         const options = {
             method: 'POST',
@@ -209,7 +238,7 @@ export const captureBase = async (captureURL, event, properties) => {
                 const success = res.statusCode === 200 || res.statusCode === 204;
                 if (!success) {
                     // Optional debug logging
-                    // console.debug(`GA tracking error: ${res.statusCode} ${data}`);
+                    // console.debug(`Telemetry tracking error: ${res.statusCode} ${data}`);
                 }
             });
         });
@@ -229,7 +258,7 @@ export const captureBase = async (captureURL, event, properties) => {
     }
 };
 /**
- * Build the standard event properties used by both GA4 and the telemetry proxy.
+ * Build the standard event properties used by the telemetry proxy.
  * Extracted from captureBase so both paths get identical data.
  */
 const buildEventProperties = async (properties) => {
@@ -325,16 +354,21 @@ const buildEventProperties = async (properties) => {
         app_version: VERSION,
         engagement_time_msec: "100",
         ...clientContext,
+        // Attribute events to the remote path when the in-flight tool call
+        // came from a remote device. Placed before sanitizedProperties so an
+        // explicit `remote` passed by the caller (e.g. captureRemote) wins.
+        ...(currentCallIsRemote ? { remote: String(true) } : {}),
         ...sanitizedProperties,
     };
 };
 /**
  * Send event to the telemetry proxy (direct BigQuery ingestion).
- * Runs in parallel with GA4 — used for high-volume events to avoid
- * the 1M/day GA4 BigQuery export limit.
+ * Uses the custom domain first and retries the generated Cloud Run URL on failure.
  */
 const sendToTelemetryProxy = async (event, eventProperties) => {
     try {
+        if (isTelemetryDisabledByEnv())
+            return;
         const telemetryEnabled = await configManager.getValue('telemetryEnabled');
         if (isTelemetryDisabledValue(telemetryEnabled))
             return;
@@ -346,7 +380,18 @@ const sendToTelemetryProxy = async (event, eventProperties) => {
                     params: eventProperties
                 }]
         });
-        const url = new URL(TELEMETRY_PROXY_URL);
+        const sent = await postTelemetryPayload(TELEMETRY_PROXY_URL, payload);
+        if (!sent) {
+            await postTelemetryPayload(TELEMETRY_PROXY_FALLBACK_URL, payload);
+        }
+    }
+    catch {
+        // Silent fail — telemetry should never break functionality
+    }
+};
+const postTelemetryPayload = async (endpoint, payload) => {
+    return await new Promise((resolve) => {
+        const url = new URL(endpoint);
         const options = {
             hostname: url.hostname,
             port: 443,
@@ -354,59 +399,40 @@ const sendToTelemetryProxy = async (event, eventProperties) => {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                'Authorization': `Bearer ${TELEMETRY_PROXY_TOKEN}`,
                 'Content-Length': Buffer.byteLength(payload)
             }
         };
         const req = https.request(options, (res) => {
-            res.resume(); // drain response
+            res.resume();
+            res.on('end', () => resolve(res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300));
+        });
+        req.on('error', () => resolve(false));
+        req.setTimeout(3000, () => {
+            req.destroy();
+            resolve(false);
         });
-        req.on('error', () => { }); // silent fail
-        req.setTimeout(3000, () => req.destroy());
         req.write(payload);
         req.end();
-    }
-    catch {
-        // Silent fail — telemetry should never break functionality
-    }
-};
-export const capture_call_tool = async (event, properties) => {
-    // Old property (G-8L163XZ1CE) — keeps lower-volume tool events
-    const GA_OLD_ID = 'G-8L163XZ1CE';
-    const GA_OLD_SECRET = 'hNxh4TK2TnSy4oLZn4RwTA';
-    const GA_OLD_URL = `https://www.google-analytics.com/mp/collect?measurement_id=${GA_OLD_ID}&api_secret=${GA_OLD_SECRET}`;
-    // New property (dc_high_volume) — receives highest-volume tool events to avoid 1M/day BQ export limit
-    const GA_NEW_ID = 'G-ZDF1M5403Z';
-    const GA_NEW_SECRET = 'cUEilpa0SpWfc2UjblDtKQ';
-    const GA_NEW_URL = `https://www.google-analytics.com/mp/collect?measurement_id=${GA_NEW_ID}&api_secret=${GA_NEW_SECRET}`;
-    // Route highest-volume tools to new property, rest to old
-    const HIGH_VOLUME_TOOLS = ['start_process', 'track_ui_event'];
-    const toolName = properties?.tool_name ?? properties?.name;
-    const gaUrl = HIGH_VOLUME_TOOLS.includes(toolName) ? GA_NEW_URL : GA_OLD_URL;
-    // Build properties once, send to GA4 + telemetry proxy in parallel
-    const eventProperties = await buildEventProperties(properties);
-    await Promise.all([
-        captureBase(gaUrl, event, properties), // GA4 (routed by tool name)
-        sendToTelemetryProxy(event, eventProperties), // direct BigQuery (all events)
-    ]);
+    });
 };
+// TODO(behavior): capture() is now fire-and-forget — every `await capture(...)`
+// call site resolves before the network send completes. Fine for the long-running
+// MCP server, but events fired right before process exit (e.g. opt-out, feedback)
+// can be silently dropped. If we need delivery guarantees on short-lived paths,
+// expose an awaitable variant or flush-before-exit hook.
 export const capture = async (event, properties) => {
-    const GA_MEASUREMENT_ID = 'G-F3GK01G39Y';
-    const GA_API_SECRET = 'SqdcIAweSQS1RQErURMdEA';
-    const GA_BASE_URL = `https://www.google-analytics.com/mp/collect?measurement_id=${GA_MEASUREMENT_ID}&api_secret=${GA_API_SECRET}`;
-    // Build properties once, send to both GA4 and telemetry proxy in parallel
-    const eventProperties = await buildEventProperties(properties);
-    await Promise.all([
-        captureBase(GA_BASE_URL, event, properties), // existing GA4
-        sendToTelemetryProxy(event, eventProperties), // new: direct BigQuery
-    ]);
-};
-export const capture_ui_event = async (event, properties) => {
-    const GA_MEASUREMENT_ID = 'G-MPFSWEGQ0T';
-    const GA_API_SECRET = 'BeK3uyAOQ6-TK6wnaDG2Ww';
-    const GA_BASE_URL = `https://www.google-analytics.com/mp/collect?measurement_id=${GA_MEASUREMENT_ID}&api_secret=${GA_API_SECRET}`;
-    return await captureBase(GA_BASE_URL, event, properties);
+    void (async () => {
+        try {
+            const eventProperties = await buildEventProperties(properties);
+            await sendToTelemetryProxy(event, eventProperties);
+        }
+        catch {
+            // Silent fail — telemetry should never break functionality
+        }
+    })();
 };
+export const capture_call_tool = capture;
+export const capture_ui_event = capture;
 /**
  * Wrapper for capture() that automatically adds remote flag for remote-device telemetry
  * Also adds additional privacy filtering to remove sensitive identity information

package/dist/utils/feature-flags.d.ts

@@ -33,6 +33,9 @@ declare class FeatureFlagManager {
      * 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
      */
     waitForFreshFlags(): Promise<void>;
     /**

package/dist/utils/feature-flags.js

@@ -93,10 +93,24 @@ class FeatureFlagManager {
      * 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) {
-            await 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);
+                }
+            }
         }
     }
     /**
@@ -127,17 +141,26 @@ class FeatureFlagManager {
      * 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
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), 5000);
-            const response = await fetch(this.flagUrl, {
+            // 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',
                 }
             });
-            clearTimeout(timeout);
+            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}`);
             }
@@ -155,6 +178,12 @@ class FeatureFlagManager {
             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

package/dist/utils/files/excel.js

@@ -25,8 +25,10 @@ export class ExcelFileHandler {
         const paginationInfo = totalRows > returnedRows
             ? `\n[Showing rows ${(options?.offset || 0) + 1}-${(options?.offset || 0) + returnedRows} of ${totalRows} total. Use offset/length to paginate.]`
             : '';
+        const sheetHasSpace = /\s/.test(sheetName);
+        const exampleSheet = sheetHasSpace ? sheetName : 'Sheet1';
         const content = `[Sheet: '${sheetName}' from ${path}]${paginationInfo}
-[To MODIFY cells: use edit_block with range param, e.g., edit_block(path, {range: "Sheet1!E5", content: [[newValue]]})]
+[To MODIFY cells: use edit_block with range param, e.g., edit_block(path, {range: "${exampleSheet}!E5", content: [[newValue]]}). read_file accepts the same range form, or pass sheet + range separately.]
 
 ${JSON.stringify(data)}`;
         return {
@@ -260,6 +262,17 @@ ${JSON.stringify(data)}`;
         if (workbook.worksheets.length === 0) {
             return { sheetName: '', data: [], totalRows: 0, returnedRows: 0 };
         }
+        // Accept range with embedded sheet prefix (parity with edit_block).
+        // E.g. range:"Sheet1!A1:B2" or "'My Sheet'!A1" — strip the sheet
+        // prefix and, when the caller did not pass an explicit sheet, use it.
+        let cellRangeOnly = range;
+        if (range && range.includes('!')) {
+            const [sheetFromRange, cellsFromRange] = this.parseRange(range);
+            cellRangeOnly = cellsFromRange ?? undefined;
+            if (sheetRef === undefined && sheetFromRange) {
+                sheetRef = sheetFromRange;
+            }
+        }
         // Find target worksheet
         let worksheet;
         let sheetName;
@@ -287,8 +300,8 @@ ${JSON.stringify(data)}`;
         let endRow = worksheet.actualRowCount || 1;
         let startCol = 1;
         let endCol = worksheet.actualColumnCount || 1;
-        if (range) {
-            const parsed = this.parseCellRange(range);
+        if (cellRangeOnly) {
+            const parsed = this.parseCellRange(cellRangeOnly);
             startRow = parsed.startRow;
             startCol = parsed.startCol;
             if (parsed.endRow)
@@ -386,7 +399,14 @@ ${JSON.stringify(data)}`;
     }
     parseRange(range) {
         if (range.includes('!')) {
-            const [sheetName, cellRange] = range.split('!');
+            const idx = range.indexOf('!');
+            let sheetName = range.slice(0, idx);
+            const cellRange = range.slice(idx + 1);
+            // Strip Excel-native single quotes around sheet names with spaces:
+            // 'My Sheet'!A1 → My Sheet, A1
+            if (sheetName.length >= 2 && sheetName.startsWith("'") && sheetName.endsWith("'")) {
+                sheetName = sheetName.slice(1, -1).replace(/''/g, "'");
+            }
             return [sheetName, cellRange];
         }
         return [range, null];
@@ -395,7 +415,8 @@ ${JSON.stringify(data)}`;
         // Parse A1 or A1:C10 format
         const match = range.match(/^([A-Z]+)(\d+)(?::([A-Z]+)(\d+))?$/i);
         if (!match) {
-            throw new Error(`Invalid cell range: ${range}`);
+            throw new Error(`Invalid cell range: "${range}". Expected forms: "A1", "A1:C10", or "SheetName!A1:C10" ` +
+                `(single-quote sheet names containing spaces: "'My Sheet'!A1:C10").`);
         }
         const startCol = this.columnToNumber(match[1]);
         const startRow = parseInt(match[2], 10);

package/dist/utils/mcp-ui-ab-test.d.ts

@@ -0,0 +1,13 @@
+export declare const MCP_UI_EXPERIMENT_NAME = "McpUiPreviews";
+export declare const MCP_UI_SHOW_VARIANT = "showMCPUi";
+export declare const MCP_UI_HIDE_VARIANT = "notShowMCPUi";
+export interface McpUiPreviewDecisionDeps {
+    getExistingAssignment: () => Promise<unknown>;
+    isFirstRun: () => boolean;
+    wasLoadedFromCache: () => boolean;
+    waitForFreshFlags: () => Promise<void>;
+    getABTestVariant: (experimentName: string) => Promise<string | null>;
+    capture: (event: string, properties?: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+export declare function resolveMcpUiPreviewDecision(deps: McpUiPreviewDecisionDeps): Promise<boolean>;
+export declare function shouldShowMcpUiPreviews(): Promise<boolean>;

package/dist/utils/mcp-ui-ab-test.js

@@ -0,0 +1,62 @@
+import { configManager } from '../config-manager.js';
+import { getABTestVariant } from './ab-test.js';
+import { capture } from './capture.js';
+import { featureFlagManager } from './feature-flags.js';
+export const MCP_UI_EXPERIMENT_NAME = 'McpUiPreviews';
+export const MCP_UI_SHOW_VARIANT = 'showMCPUi';
+export const MCP_UI_HIDE_VARIANT = 'notShowMCPUi';
+function variantEnablesMcpUi(variant) {
+    if (variant === MCP_UI_HIDE_VARIANT)
+        return false;
+    if (variant === MCP_UI_SHOW_VARIANT)
+        return true;
+    return null;
+}
+export async function resolveMcpUiPreviewDecision(deps) {
+    try {
+        const existingAssignment = await deps.getExistingAssignment();
+        const existingDecision = variantEnablesMcpUi(existingAssignment);
+        if (existingDecision !== null) {
+            if (!deps.wasLoadedFromCache()) {
+                await deps.waitForFreshFlags();
+            }
+            const currentVariant = await deps.getABTestVariant(MCP_UI_EXPERIMENT_NAME);
+            return variantEnablesMcpUi(currentVariant) ?? existingDecision;
+        }
+        if (!deps.isFirstRun()) {
+            return true;
+        }
+        if (!deps.wasLoadedFromCache()) {
+            await deps.waitForFreshFlags();
+        }
+        const variant = await deps.getABTestVariant(MCP_UI_EXPERIMENT_NAME);
+        const decision = variantEnablesMcpUi(variant);
+        if (decision === null) {
+            return true;
+        }
+        try {
+            await deps.capture('server_mcp_ui_ab_decision', {
+                experiment: MCP_UI_EXPERIMENT_NAME,
+                variant,
+                mcp_ui_enabled: decision,
+            });
+        }
+        catch {
+            // Telemetry must not change the assigned product experience.
+        }
+        return decision;
+    }
+    catch {
+        return true;
+    }
+}
+export async function shouldShowMcpUiPreviews() {
+    return resolveMcpUiPreviewDecision({
+        getExistingAssignment: () => configManager.getValue(`abTest_${MCP_UI_EXPERIMENT_NAME}`),
+        isFirstRun: () => configManager.isFirstRun(),
+        wasLoadedFromCache: () => featureFlagManager.wasLoadedFromCache(),
+        waitForFreshFlags: () => featureFlagManager.waitForFreshFlags(),
+        getABTestVariant,
+        capture,
+    });
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonderwhy-er/desktop-commander",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "MCP server for terminal operations and file editing",
   "mcpName": "io.github.wonderwhy-er/desktop-commander",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "prepare": "npm run build",
     "clean": "shx rm -rf dist",
     "test": "npm run build && node test/run-all-tests.js",
+    "test:integration": "npm run build && node test/integration/run-all-integration-tests.js",
     "test:debug": "node --inspect test/run-all-tests.js",
     "validate:tools": "npm run build && node scripts/validate-tools-sync.js",
     "link:local": "npm run build && npm link",