Merge remote-tracking branch 'upstream/main' into gothic-vicuna

# Conflicts:
#	src/extension.ts
#	src/internal.api.ts

Author: eleanorjboyd

.vscode/settings.json

@@ -31,6 +31,7 @@
     "git.branchProtectionPrompt": "alwaysCommitToNewBranch",
     "chat.tools.terminal.autoApprove": {
         "npx tsc": true,
-        "mkdir": true
+        "mkdir": true,
+        "npx mocha": true
     }
 }

src/common/constants.ts

@@ -4,6 +4,7 @@ export const ENVS_EXTENSION_ID = 'ms-python.vscode-python-envs';
 export const PYTHON_EXTENSION_ID = 'ms-python.python';
 export const JUPYTER_EXTENSION_ID = 'ms-toolsai.jupyter';
 export const EXTENSION_ROOT_DIR = path.dirname(__dirname);
+export const ISSUES_URL = 'https://github.com/microsoft/vscode-python-environments/issues';
 
 export const DEFAULT_PACKAGE_MANAGER_ID = 'ms-python.python:pip';
 export const DEFAULT_ENV_MANAGER_ID = 'ms-python.python:venv';

src/common/telemetry/constants.ts

@@ -49,6 +49,7 @@ export enum EventNames {
      * - errorType: string (error class name, on failure only)
      */
     ENVIRONMENT_DISCOVERY = 'ENVIRONMENT_DISCOVERY',
+    MANAGER_READY_TIMEOUT = 'MANAGER_READY.TIMEOUT',
 }
 
 // Map all events to their properties
@@ -227,4 +228,15 @@ export interface IEventNamePropertyMapping {
         envCount?: number;
         errorType?: string;
     };
+
+    /* __GDPR__
+        "manager_ready.timeout": {
+            "managerId": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "managerKind": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.MANAGER_READY_TIMEOUT]: {
+        managerId: string;
+        managerKind: 'environment' | 'package';
+    };
 }

src/common/telemetry/helpers.ts

@@ -1,7 +1,8 @@
 import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../../features/settings/settingHelpers';
 import { EnvironmentManagers, PythonProjectManager } from '../../internal.api';
 import { getUvEnvironments } from '../../managers/builtin/uvEnvironments';
-import { traceVerbose } from '../logging';
+import { ISSUES_URL } from '../constants';
+import { traceInfo, traceVerbose, traceWarn } from '../logging';
 import { getWorkspaceFolders } from '../workspace.apis';
 import { EventNames } from './constants';
 import { sendTelemetryEvent } from './sender';
@@ -154,3 +155,37 @@ export async function sendEnvironmentToolUsageTelemetry(
         traceVerbose('Failed to send environment tool usage telemetry:', error);
     }
 }
+
+/**
+ * Logs a summary of environment discovery results after startup.
+ * If no environments are found, logs guidance to help users troubleshoot.
+ */
+export async function logDiscoverySummary(envManagers: EnvironmentManagers): Promise<void> {
+    const managers = envManagers.managers;
+    let totalEnvCount = 0;
+    const managerSummaries: string[] = [];
+
+    for (const manager of managers) {
+        try {
+            const envs = await manager.getEnvironments('all');
+            totalEnvCount += envs.length;
+            if (envs.length > 0) {
+                managerSummaries.push(`${manager.displayName}: ${envs.length}`);
+            }
+        } catch {
+            // Discovery errors are already logged by InternalEnvironmentManager.refresh()
+        }
+    }
+
+    if (totalEnvCount === 0) {
+        traceWarn(
+            `No Python environments were found. ` +
+                `Try running "Python Environments: Run Python Environment Tool (PET) in Terminal..." from the Command Palette to diagnose. ` +
+                `If environments should be detected, please report this: ${ISSUES_URL}/new`,
+        );
+    } else {
+        traceInfo(
+            `Environment discovery complete: ${totalEnvCount} environments found (${managerSummaries.join(', ')})`,
+        );
+    }
+}

src/common/utils/asyncUtils.ts

@@ -1,3 +1,17 @@
+import { traceError } from '../logging';
+
 export async function timeout(milliseconds: number): Promise<void> {
     return new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
 }
+
+/**
+ * Wraps a promise so that rejection is caught and logged instead of propagated.
+ * Use with `Promise.all` to run tasks independently — one failure won't block the others.
+ */
+export async function safeRegister(name: string, task: Promise<void>): Promise<void> {
+    try {
+        await task;
+    } catch (error) {
+        traceError(`Failed to register ${name} features:`, error);
+    }
+}

src/extension.ts

@@ -18,11 +18,13 @@ import { newProjectSelection } from './common/pickers/managers';
 import { StopWatch } from './common/stopWatch';
 import { EventNames } from './common/telemetry/constants';
 import {
+    logDiscoverySummary,
     sendEnvironmentToolUsageTelemetry,
     sendManagerSelectionTelemetry,
     sendProjectStructureTelemetry,
 } from './common/telemetry/helpers';
 import { sendTelemetryEvent } from './common/telemetry/sender';
+import { safeRegister } from './common/utils/asyncUtils';
 import { createDeferred } from './common/utils/deferred';
 
 import {
@@ -526,13 +528,23 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             context.subscriptions.push(nativeFinder);
             const sysMgr = new SysPythonManager(nativeFinder, api, outputChannel);
             sysPythonManager.resolve(sysMgr);
+            // Each manager registers independently — one failure must not block the others.
             await Promise.all([
-                registerSystemPythonFeatures(nativeFinder, context.subscriptions, outputChannel, sysMgr),
-                registerCondaFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
-                registerPyenvFeatures(nativeFinder, context.subscriptions, projectManager),
-                registerPipenvFeatures(nativeFinder, context.subscriptions, projectManager),
-                registerPoetryFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
-                shellStartupVarsMgr.initialize(),
+                safeRegister(
+                    'system',
+                    registerSystemPythonFeatures(nativeFinder, context.subscriptions, outputChannel, sysMgr),
+                ),
+                safeRegister(
+                    'conda',
+                    registerCondaFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
+                ),
+                safeRegister('pyenv', registerPyenvFeatures(nativeFinder, context.subscriptions, projectManager)),
+                safeRegister('pipenv', registerPipenvFeatures(nativeFinder, context.subscriptions, projectManager)),
+                safeRegister(
+                    'poetry',
+                    registerPoetryFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
+                ),
+                safeRegister('shellStartupVars', shellStartupVarsMgr.initialize()),
             ]);
 
             await applyInitialEnvironmentSelection(envManagers, projectManager, nativeFinder, api);
@@ -550,7 +562,10 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 await terminalManager.initialize(api);
                 sendManagerSelectionTelemetry(projectManager);
                 await sendProjectStructureTelemetry(projectManager, envManagers);
-              await sendEnvironmentToolUsageTelemetry(projectManager, envManagers);
+                await sendEnvironmentToolUsageTelemetry(projectManager, envManagers);
+
+                // Log discovery summary to help users troubleshoot environment detection issues
+                await logDiscoverySummary(envManagers);
             } catch (postInitError) {
                 traceError('Post-initialization tasks failed:', postInitError);
             }

src/features/common/managerReady.ts

@@ -1,12 +1,16 @@
 import { Disposable, l10n, Uri } from 'vscode';
-import { EnvironmentManagers, PythonProjectManager } from '../../internal.api';
-import { createDeferred, Deferred } from '../../common/utils/deferred';
 import { allExtensions, getExtension } from '../../common/extension.apis';
-import { traceError, traceInfo } from '../../common/logging';
-import { showErrorMessage } from '../../common/window.apis';
-import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../settings/settingHelpers';
 import { WorkbenchStrings } from '../../common/localize';
+import { traceError, traceInfo, traceWarn } from '../../common/logging';
+import { EventNames } from '../../common/telemetry/constants';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
+import { createDeferred, Deferred } from '../../common/utils/deferred';
+import { showErrorMessage } from '../../common/window.apis';
 import { installExtension } from '../../common/workbenchCommands';
+import { EnvironmentManagers, PythonProjectManager } from '../../internal.api';
+import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../settings/settingHelpers';
+
+const MANAGER_READY_TIMEOUT_MS = 30_000;
 
 interface ManagerReady extends Disposable {
     waitForEnvManager(uris?: Uri[]): Promise<void>;
@@ -29,7 +33,10 @@ class ManagerReadyImpl implements ManagerReady {
     private readonly checked: Set<string> = new Set();
     private readonly disposables: Disposable[] = [];
 
-    constructor(em: EnvironmentManagers, private readonly pm: PythonProjectManager) {
+    constructor(
+        em: EnvironmentManagers,
+        private readonly pm: PythonProjectManager,
+    ) {
         this.disposables.push(
             em.onDidChangeEnvironmentManager((e) => {
                 if (this.envManagers.has(e.manager.id)) {
@@ -104,6 +111,44 @@ class ManagerReadyImpl implements ManagerReady {
         }
     }
 
+    /**
+     * Wraps a deferred with a timeout so a missing/dead manager cannot block the API forever.
+     * On timeout the deferred is resolved (not rejected) so callers proceed with degraded results
+     * instead of hanging.
+     */
+    private _withTimeout(deferred: Deferred<void>, managerId: string, kind: string): Promise<void> {
+        if (deferred.completed) {
+            return deferred.promise;
+        }
+        return new Promise<void>((resolve) => {
+            const timer = setTimeout(() => {
+                if (!deferred.completed) {
+                    traceWarn(
+                        `Timed out after ${MANAGER_READY_TIMEOUT_MS / 1000}s waiting for ${kind} manager "${managerId}" to register. ` +
+                            `The manager may not be installed or its extension failed to activate. Proceeding without it. ` +
+                            `To prevent this, check your "python-envs.defaultEnvManager" and "python-envs.pythonProjects" settings.`,
+                    );
+                    sendTelemetryEvent(EventNames.MANAGER_READY_TIMEOUT, undefined, {
+                        managerId,
+                        managerKind: kind as 'environment' | 'package',
+                    });
+                    deferred.resolve();
+                }
+            }, MANAGER_READY_TIMEOUT_MS);
+
+            deferred.promise.then(
+                () => {
+                    clearTimeout(timer);
+                    resolve();
+                },
+                () => {
+                    clearTimeout(timer);
+                    resolve();
+                },
+            );
+        });
+    }
+
     public dispose(): void {
         this.disposables.forEach((d) => d.dispose());
         this.envManagers.clear();
@@ -116,7 +161,7 @@ class ManagerReadyImpl implements ManagerReady {
         }
         const deferred = createDeferred<void>();
         this.envManagers.set(managerId, deferred);
-        return deferred.promise;
+        return this._withTimeout(deferred, managerId, 'environment');
     }
 
     public async waitForEnvManager(uris?: Uri[]): Promise<void> {
@@ -165,7 +210,7 @@ class ManagerReadyImpl implements ManagerReady {
         }
         const deferred = createDeferred<void>();
         this.pkgManagers.set(managerId, deferred);
-        return deferred.promise;
+        return this._withTimeout(deferred, managerId, 'package');
     }
 
     public async waitForPkgManager(uris?: Uri[]): Promise<void> {

src/internal.api.ts

@@ -27,7 +27,9 @@ import {
     ResolveEnvironmentContext,
     SetEnvironmentScope,
 } from './api';
+import { ISSUES_URL } from './common/constants';
 import { CreateEnvironmentNotSupported, RemoveEnvironmentNotSupported } from './common/errors/NotSupportedError';
+import { traceWarn } from './common/logging';
 import { StopWatch } from './common/stopWatch';
 import { EventNames } from './common/telemetry/constants';
 import { sendTelemetryEvent } from './common/telemetry/sender';
@@ -205,26 +207,47 @@ export class InternalEnvironmentManager implements EnvironmentManager {
 
     async refresh(options: RefreshEnvironmentsScope): Promise<void> {
         const sw = new StopWatch();
+        const SLOW_DISCOVERY_THRESHOLD_MS = 15000;
         try {
             await this.manager.refresh(options);
             const envs = await this.manager.getEnvironments('all').catch(() => []);
-            sendTelemetryEvent(EventNames.ENVIRONMENT_DISCOVERY, sw.elapsedTime, {
+            const duration = sw.elapsedTime;
+            sendTelemetryEvent(EventNames.ENVIRONMENT_DISCOVERY, duration, {
                 managerId: this.id,
                 result: 'success',
                 envCount: envs.length,
             });
+
+            // Log warning for slow discovery
+            if (duration > SLOW_DISCOVERY_THRESHOLD_MS) {
+                traceWarn(
+                    `[${this.displayName}] Environment discovery took ${(duration / 1000).toFixed(1)}s (found ${envs.length} environments). ` +
+                        `If this is causing problems, please report it: ${ISSUES_URL}/new`,
+                );
+            }
         } catch (ex) {
+            const duration = sw.elapsedTime;
             const errorType = classifyError(ex);
             sendTelemetryEvent(
                 EventNames.ENVIRONMENT_DISCOVERY,
-                sw.elapsedTime,
+                duration,
                 {
                     managerId: this.id,
                     result: errorType === 'canceled' || errorType === 'spawn_timeout' ? 'timeout' : 'error',
                     errorType,
                 },
                 ex instanceof Error ? ex : undefined,
             );
+
+            // Log verbose failure message to help users report issues
+            const errorMessage = ex instanceof Error ? ex.message : String(ex);
+            traceWarn(
+                `[${this.displayName}] Environment discovery failed after ${(duration / 1000).toFixed(1)}s.\n` +
+                    `  Error: ${errorType} - ${errorMessage}\n` +
+                    `  If environments are not being detected correctly, please report this issue:\n` +
+                    `  ${ISSUES_URL}/new`,
+            );
+
             throw ex;
         }
     }

src/test/common/asyncUtils.unit.test.ts

@@ -0,0 +1,69 @@
+import assert from 'assert';
+import * as sinon from 'sinon';
+import * as logging from '../../common/logging';
+import { safeRegister } from '../../common/utils/asyncUtils';
+
+suite('safeRegister', () => {
+    let traceErrorStub: sinon.SinonStub;
+
+    setup(() => {
+        traceErrorStub = sinon.stub(logging, 'traceError');
+    });
+
+    teardown(() => {
+        sinon.restore();
+    });
+
+    test('resolves when the task succeeds', async () => {
+        await safeRegister('test-manager', Promise.resolve());
+        assert.ok(traceErrorStub.notCalled, 'traceError should not be called on success');
+    });
+
+    test('resolves (not rejects) when the task fails', async () => {
+        const failing = Promise.reject(new Error('boom'));
+        // safeRegister must not propagate the rejection
+        await safeRegister('failing-manager', failing);
+        // If we got here without throwing, the test passes
+    });
+
+    test('logs the manager name and error when the task fails', async () => {
+        const error = new Error('registration exploded');
+        await safeRegister('conda', Promise.reject(error));
+
+        assert.ok(traceErrorStub.calledOnce, 'traceError should be called once');
+        const [message, loggedError] = traceErrorStub.firstCall.args;
+        assert.ok(message.includes('conda'), 'log message should contain the manager name');
+        assert.strictEqual(loggedError, error, 'original error should be passed through');
+    });
+
+    test('independent tasks continue when one fails', async () => {
+        const results: string[] = [];
+
+        await Promise.all([
+            safeRegister('will-fail', Promise.reject(new Error('fail'))),
+            safeRegister(
+                'will-succeed-1',
+                Promise.resolve().then(() => {
+                    results.push('a');
+                }),
+            ),
+            safeRegister(
+                'will-succeed-2',
+                Promise.resolve().then(() => {
+                    results.push('b');
+                }),
+            ),
+        ]);
+
+        assert.deepStrictEqual(results.sort(), ['a', 'b'], 'both successful tasks should complete');
+        assert.ok(traceErrorStub.calledOnce, 'only the failing task should log an error');
+    });
+
+    test('handles non-Error rejections', async () => {
+        await safeRegister('string-reject', Promise.reject('just a string'));
+
+        assert.ok(traceErrorStub.calledOnce);
+        const [, loggedError] = traceErrorStub.firstCall.args;
+        assert.strictEqual(loggedError, 'just a string');
+    });
+});