@wonderwhy-er/desktop-commander 0.2.24 → 0.2.26

package/dist/config-manager.d.ts

@@ -20,6 +20,7 @@ declare class ConfigManager {
     private configPath;
     private config;
     private initialized;
+    private _isFirstRun;
     constructor();
     /**
      * Initialize configuration - load from disk or create default
@@ -57,6 +58,10 @@ declare class ConfigManager {
      * Reset configuration to defaults
      */
     resetConfig(): Promise<ServerConfig>;
+    /**
+     * Check if this is the first run (config file was just created)
+     */
+    isFirstRun(): boolean;
 }
 export declare const configManager: ConfigManager;
 export {};

package/dist/config-manager.js

@@ -12,6 +12,7 @@ class ConfigManager {
     constructor() {
         this.config = {};
         this.initialized = false;
+        this._isFirstRun = false; // Track if this is the first run (config was just created)
         // Get user's home directory
         // Define config directory and file paths
         this.configPath = CONFIG_FILE;
@@ -34,10 +35,12 @@ class ConfigManager {
                 // Load existing config
                 const configData = await fs.readFile(this.configPath, 'utf8');
                 this.config = JSON.parse(configData);
+                this._isFirstRun = false;
             }
             catch (error) {
                 // Config file doesn't exist, create default
                 this.config = this.getDefaultConfig();
+                this._isFirstRun = true; // This is a first run!
                 await this.saveConfig();
             }
             this.config['version'] = VERSION;
@@ -184,6 +187,12 @@ class ConfigManager {
         await this.saveConfig();
         return { ...this.config };
     }
+    /**
+     * Check if this is the first run (config file was just created)
+     */
+    isFirstRun() {
+        return this._isFirstRun;
+    }
 }
 // Export singleton instance
 export const configManager = new ConfigManager();

package/dist/server.d.ts

@@ -7,6 +7,9 @@ export declare const server: Server<{
         _meta?: {
             [x: string]: unknown;
             progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
         } | undefined;
     } | undefined;
 }, {
@@ -15,12 +18,20 @@ export declare const server: Server<{
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
         } | undefined;
     } | undefined;
 }, {
     [x: string]: unknown;
     _meta?: {
         [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
     } | undefined;
 }>;
 declare let currentClient: {

package/dist/server.js

@@ -17,6 +17,7 @@ import { trackToolCall } from './utils/trackTools.js';
 import { usageTracker } from './utils/usageTracker.js';
 import { processDockerPrompt } from './utils/dockerPrompt.js';
 import { toolHistory } from './utils/toolHistory.js';
+import { handleWelcomePageOnboarding } from './utils/welcome-onboarding.js';
 import { VERSION } from './version.js';
 import { capture, capture_call_tool } from "./utils/capture.js";
 import { logToStderr, logger } from './utils/logger.js';
@@ -77,6 +78,10 @@ server.setRequestHandler(InitializeRequestSchema, async (request) => {
             }
             // Defer client connection message until after initialization
             deferLog('info', `Client connected: ${currentClient.name} v${currentClient.version}`);
+            // Welcome page for new claude-ai users (A/B test controlled)
+            if (currentClient.name === 'claude-ai' && !global.disableOnboarding) {
+                await handleWelcomePageOnboarding();
+            }
         }
         capture('run_server_mcp_initialized');
         // Return standard initialization response
@@ -360,6 +365,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(CreateDirectoryArgsSchema),
+                annotations: {
+                    title: "Create Directory",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                },
             },
             {
                 name: "list_directory",
@@ -499,6 +509,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(StartSearchArgsSchema),
+                annotations: {
+                    title: "Start Search",
+                    readOnlyHint: true,
+                },
             },
             {
                 name: "get_more_search_results",
@@ -544,6 +558,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(StopSearchArgsSchema),
+                annotations: {
+                    title: "Stop Search",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                },
             },
             {
                 name: "list_searches",
@@ -958,6 +977,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(GiveFeedbackArgsSchema),
+                annotations: {
+                    title: "Give Feedback",
+                    readOnlyHint: false,
+                    openWorldHint: true,
+                },
             },
             {
                 name: "get_prompts",
@@ -985,6 +1009,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
                         ${CMD_PREFIX_DESCRIPTION}`,
                 inputSchema: zodToJsonSchema(GetPromptsArgsSchema),
+                annotations: {
+                    title: "Get Prompts",
+                    readOnlyHint: true,
+                },
             }
         ];
         // Filter tools based on current client

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

@@ -0,0 +1,8 @@
+/**
+ * Check if a feature (variant name) is enabled for current user
+ */
+export declare function hasFeature(featureName: string): Promise<boolean>;
+/**
+ * Get all A/B test assignments for analytics (reads from config)
+ */
+export declare function getABTestAssignments(): Promise<Record<string, string>>;

package/dist/utils/ab-test.js

@@ -0,0 +1,76 @@
+import { configManager } from '../config-manager.js';
+import { featureFlagManager } from './feature-flags.js';
+// Cache for variant assignments (loaded once per session)
+const variantCache = {};
+/**
+ * Get experiments config from feature flags
+ */
+function getExperiments() {
+    return featureFlagManager.get('experiments', {});
+}
+/**
+ * Get user's variant for an experiment (cached, deterministic)
+ */
+async function getVariant(experimentName) {
+    const experiments = getExperiments();
+    const experiment = experiments[experimentName];
+    if (!experiment?.variants?.length)
+        return null;
+    // Check cache
+    if (variantCache[experimentName]) {
+        return variantCache[experimentName];
+    }
+    // Check persisted assignment
+    const configKey = `abTest_${experimentName}`;
+    const existing = await configManager.getValue(configKey);
+    if (existing && experiment.variants.includes(existing)) {
+        variantCache[experimentName] = existing;
+        return existing;
+    }
+    // New assignment based on clientId
+    const clientId = await configManager.getValue('clientId') || '';
+    const hash = hashCode(clientId + experimentName);
+    const variantIndex = hash % experiment.variants.length;
+    const variant = experiment.variants[variantIndex];
+    await configManager.setValue(configKey, variant);
+    variantCache[experimentName] = variant;
+    return variant;
+}
+/**
+ * Check if a feature (variant name) is enabled for current user
+ */
+export async function hasFeature(featureName) {
+    const experiments = getExperiments();
+    if (!experiments || typeof experiments !== 'object')
+        return false;
+    for (const [expName, experiment] of Object.entries(experiments)) {
+        if (experiment?.variants?.includes(featureName)) {
+            const variant = await getVariant(expName);
+            return variant === featureName;
+        }
+    }
+    return false;
+}
+/**
+ * Get all A/B test assignments for analytics (reads from config)
+ */
+export async function getABTestAssignments() {
+    const experiments = getExperiments();
+    const assignments = {};
+    for (const expName of Object.keys(experiments)) {
+        const configKey = `abTest_${expName}`;
+        const variant = await configManager.getValue(configKey);
+        if (variant) {
+            assignments[`ab_${expName}`] = variant;
+        }
+    }
+    return assignments;
+}
+function hashCode(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) - hash) + str.charCodeAt(i);
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}

package/dist/utils/capture.js

@@ -86,6 +86,11 @@ export const captureBase = async (captureURL, event, properties) => {
                 client_version: currentClient.version,
             };
         }
+        // Track if user saw onboarding page
+        const sawOnboardingPage = await configManager.getValue('sawOnboardingPage');
+        if (sawOnboardingPage !== undefined) {
+            clientContext = { ...clientContext, saw_onboarding_page: sawOnboardingPage };
+        }
         // Create a deep copy of properties to avoid modifying the original objects
         // This ensures we don't alter error objects that are also returned to the AI
         let sanitizedProperties;

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

@@ -5,6 +5,9 @@ declare class FeatureFlagManager {
     private cacheMaxAge;
     private flagUrl;
     private refreshInterval;
+    private freshFetchPromise;
+    private resolveFreshFetch;
+    private loadedFromCache;
     constructor();
     /**
      * Initialize - load from cache and start background refresh
@@ -22,6 +25,16 @@ declare class FeatureFlagManager {
      * Manually refresh flags immediately (for testing)
      */
     refresh(): Promise<boolean>;
+    /**
+     * Check if flags were loaded from cache (vs fresh fetch)
+     */
+    wasLoadedFromCache(): boolean;
+    /**
+     * 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)
+     */
+    waitForFreshFlags(): Promise<void>;
     /**
      * Load flags from local cache
      */

package/dist/utils/feature-flags.js

@@ -9,11 +9,19 @@ class FeatureFlagManager {
         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
         this.flagUrl = process.env.DC_FLAG_URL ||
             'https://desktopcommander.app/flags/v1/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
@@ -23,8 +31,17 @@ class FeatureFlagManager {
             // Load from cache immediately (non-blocking)
             await this.loadFromCache();
             // Fetch in background (don't block startup)
-            this.fetchFlags().catch(err => {
+            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(() => {
@@ -66,6 +83,22 @@ class FeatureFlagManager {
             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)
+     */
+    async waitForFreshFlags() {
+        if (this.freshFetchPromise) {
+            await this.freshFetchPromise;
+        }
+    }
     /**
      * Load flags from local cache
      */
@@ -73,6 +106,7 @@ class FeatureFlagManager {
         try {
             if (!existsSync(this.cachePath)) {
                 logger.debug('No feature flag cache found');
+                this.loadedFromCache = false;
                 return;
             }
             const data = await fs.readFile(this.cachePath, 'utf8');
@@ -80,11 +114,13 @@ class FeatureFlagManager {
             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;
         }
     }
     /**

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

@@ -0,0 +1,9 @@
+/**
+ * Open a URL in the default browser (cross-platform)
+ * Uses execFile/spawn with args array to avoid shell injection
+ */
+export declare function openBrowser(url: string): Promise<void>;
+/**
+ * Open the Desktop Commander welcome page
+ */
+export declare function openWelcomePage(): Promise<void>;

package/dist/utils/open-browser.js

@@ -0,0 +1,43 @@
+import { execFile, spawn } from 'child_process';
+import os from 'os';
+import { logToStderr } from './logger.js';
+/**
+ * Open a URL in the default browser (cross-platform)
+ * Uses execFile/spawn with args array to avoid shell injection
+ */
+export async function openBrowser(url) {
+    const platform = os.platform();
+    return new Promise((resolve, reject) => {
+        const callback = (error) => {
+            if (error) {
+                logToStderr('error', `Failed to open browser: ${error.message}`);
+                reject(error);
+            }
+            else {
+                logToStderr('info', `Opened browser to: ${url}`);
+                resolve();
+            }
+        };
+        switch (platform) {
+            case 'darwin':
+                execFile('open', [url], callback);
+                break;
+            case 'win32':
+                // Windows 'start' is a shell builtin, use spawn with shell but pass URL as separate arg
+                spawn('cmd', ['/c', 'start', '', url], { shell: false }).on('close', (code) => {
+                    code === 0 ? resolve() : reject(new Error(`Exit code ${code}`));
+                });
+                break;
+            default:
+                execFile('xdg-open', [url], callback);
+                break;
+        }
+    });
+}
+/**
+ * Open the Desktop Commander welcome page
+ */
+export async function openWelcomePage() {
+    const url = 'https://desktopcommander.app/welcome/';
+    await openBrowser(url);
+}

package/dist/utils/usageTracker.js

@@ -325,6 +325,12 @@ class UsageTracker {
      * Check if user should see onboarding invitation - SIMPLE VERSION
      */
     async shouldShowOnboarding() {
+        // Check feature flag first (remote kill switch)
+        const { featureFlagManager } = await import('./feature-flags.js');
+        const onboardingEnabled = featureFlagManager.get('onboarding_injection', true);
+        if (!onboardingEnabled) {
+            return false;
+        }
         // Check if onboarding is disabled via command line argument
         if (global.disableOnboarding) {
             return false;

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

@@ -0,0 +1,9 @@
+/**
+ * Handle welcome page display for new users (A/B test controlled)
+ *
+ * Only shows to:
+ * 1. New users (first run - config was just created)
+ * 2. Users in the 'showOnboardingPage' A/B variant
+ * 3. Haven't seen it yet
+ */
+export declare function handleWelcomePageOnboarding(): Promise<void>;

package/dist/utils/welcome-onboarding.js

@@ -0,0 +1,45 @@
+import { configManager } from '../config-manager.js';
+import { hasFeature } from './ab-test.js';
+import { featureFlagManager } from './feature-flags.js';
+import { openWelcomePage } from './open-browser.js';
+import { logToStderr } from './logger.js';
+/**
+ * Handle welcome page display for new users (A/B test controlled)
+ *
+ * Only shows to:
+ * 1. New users (first run - config was just created)
+ * 2. Users in the 'showOnboardingPage' A/B variant
+ * 3. Haven't seen it yet
+ */
+export async function handleWelcomePageOnboarding() {
+    // Only for brand new users (config just created)
+    if (!configManager.isFirstRun()) {
+        return;
+    }
+    // For new users, we need to wait for feature flags to load from network
+    // since they won't have a cache file yet. Without this, hasFeature() would
+    // return false (no experiments defined) and all new users go to control.
+    if (!featureFlagManager.wasLoadedFromCache()) {
+        logToStderr('debug', 'Waiting for feature flags to load...');
+        await featureFlagManager.waitForFreshFlags();
+    }
+    // Check A/B test assignment
+    const shouldShow = await hasFeature('showOnboardingPage');
+    if (!shouldShow) {
+        logToStderr('debug', 'Welcome page skipped (A/B: noOnboardingPage)');
+        return;
+    }
+    // Double-check not already shown (safety)
+    const alreadyShown = await configManager.getValue('sawOnboardingPage');
+    if (alreadyShown) {
+        return;
+    }
+    try {
+        await openWelcomePage();
+        await configManager.setValue('sawOnboardingPage', true);
+        logToStderr('info', 'Welcome page opened');
+    }
+    catch (e) {
+        logToStderr('warning', `Failed to open welcome page: ${e instanceof Error ? e.message : e}`);
+    }
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.24";
+export declare const VERSION = "0.2.26";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.2.24';
+export const VERSION = '0.2.26';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonderwhy-er/desktop-commander",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "MCP server for terminal operations and file editing",
   "mcpName": "io.github.wonderwhy-er/desktop-commander",
   "license": "MIT",
@@ -81,11 +81,11 @@
     "@opendocsg/pdf2md": "^0.2.2",
     "@vscode/ripgrep": "^1.15.9",
     "cross-fetch": "^4.1.0",
+    "exceljs": "^4.4.0",
     "fastest-levenshtein": "^1.0.16",
     "file-type": "^21.1.1",
     "glob": "^10.3.10",
     "isbinaryfile": "^5.0.4",
-    "exceljs": "^4.4.0",
     "md-to-pdf": "^5.2.5",
     "pdf-lib": "^1.17.1",
     "remark": "^15.0.1",