Merge branch 'main' into simple-roadrunner

Author: eleanorjboyd

.github/instructions/testing-workflow.instructions.md

@@ -37,17 +37,20 @@ This guide covers the full testing lifecycle:
 
 These mistakes have occurred REPEATEDLY. Check this list BEFORE writing any test code:
 
-| Mistake                                        | Fix                                                                |
-| ---------------------------------------------- | ------------------------------------------------------------------ |
-| Hardcoded POSIX paths like `'/test/workspace'` | Use `'.'` for relative paths, `Uri.file(x).fsPath` for comparisons |
-| Stubbing `workspace.getConfiguration` directly | Stub the wrapper `workspaceApis.getConfiguration` instead          |
-| Stubbing `workspace.workspaceFolders` property | Stub wrapper function `workspaceApis.getWorkspaceFolders()`        |
-| Comparing `fsPath` to raw string               | Compare `fsPath` to `Uri.file(expected).fsPath`                    |
+| Mistake                                        | Fix                                                                                        |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Hardcoded POSIX paths like `'/test/workspace'` | Use `'.'` for relative paths, `Uri.file(x).fsPath` for comparisons                         |
+| Stubbing `workspace.getConfiguration` directly | Stub the wrapper `workspaceApis.getConfiguration` instead                                  |
+| Stubbing `workspace.workspaceFolders` property | Stub wrapper function `workspaceApis.getWorkspaceFolders()`                                |
+| Comparing `fsPath` to raw string               | Compare `fsPath` to `Uri.file(expected).fsPath`                                            |
+| Stubbing `commands.executeCommand` directly    | First update production code to use `executeCommand` from `command.api.ts`, then stub that |
+| Stubbing `window.createTreeView` directly      | First update production code to use `createTreeView` from `window.apis.ts`, then stub that |
 
 **Pre-flight checklist before completing test work:**
 
 - [ ] All paths use `Uri.file().fsPath` (no hardcoded `/path/to/x`)
 - [ ] All VS Code API stubs use wrapper modules, not `vscode.*` directly
+- [ ] Production code uses wrappers for any VS Code API that tests need to stub (check `src/common/*.apis.ts`)
 - [ ] Tests pass on both Windows and POSIX
 
 ## Test Types
@@ -597,4 +600,5 @@ envConfig.inspect
 - Use `sinon.useFakeTimers()` with `clock.tickAsync()` instead of `await new Promise(resolve => setTimeout(resolve, ms))` for debounce/timeout handling - eliminates flakiness and speeds up tests significantly (1)
 - Always compile tests (`npm run compile-tests`) before running them after adding new test cases - test counts will be wrong if running against stale compiled output (1)
 - Never create "documentation tests" that just `assert.ok(true)` — if mocking limitations prevent testing, either test a different layer that IS mockable, or skip the test entirely with a clear explanation (1)
-- When stubbing vscode APIs in tests via wrapper modules (e.g., `workspaceApis`), the production code must also use those wrappers — sinon cannot stub properties directly on the vscode namespace like `workspace.workspaceFolders`, so both production and test code must reference the same stubbable wrapper functions (3)
+- When stubbing vscode APIs in tests via wrapper modules (e.g., `workspaceApis`), the production code must also use those wrappers — sinon cannot stub properties directly on the vscode namespace like `workspace.workspaceFolders`, so both production and test code must reference the same stubbable wrapper functions (4)
+- **Before writing tests**, check if the function under test calls VS Code APIs directly (e.g., `commands.executeCommand`, `window.createTreeView`, `workspace.getConfiguration`). If so, FIRST update the production code to use wrapper functions from `src/common/*.apis.ts` (create the wrapper if it doesn't exist), THEN write tests that stub those wrappers. This prevents CI failures where sinon cannot stub the vscode namespace (4)

package.json

@@ -6,7 +6,7 @@
     "publisher": "ms-python",
     "preview": true,
     "engines": {
-        "vscode": "^1.110.0-20260204" 
+        "vscode": "^1.110.0-20260204"
     },
     "categories": [
         "Other"
@@ -320,6 +320,12 @@
                 "category": "Python Envs",
                 "icon": "$(folder-opened)"
             },
+            {
+                "command": "python-envs.revealEnvInManagerView",
+                "title": "%python-envs.revealEnvInManagerView.title%",
+                "category": "Python Envs",
+                "icon": "$(eye)"
+            },
             {
                 "command": "python-envs.runPetInTerminal",
                 "title": "%python-envs.runPetInTerminal.title%",
@@ -430,6 +436,10 @@
                     "command": "python-envs.revealProjectInExplorer",
                     "when": "false"
                 },
+                {
+                    "command": "python-envs.revealEnvInManagerView",
+                    "when": "false"
+                },
                 {
                     "command": "python-envs.createNewProjectFromTemplate",
                     "when": "config.python.useEnvironmentsExtension != false"
@@ -453,6 +463,10 @@
                     "command": "python-envs.remove",
                     "when": "view == env-managers && viewItem =~ /.*pythonEnvironment.*;remove;.*/"
                 },
+                {
+                    "command": "python-envs.remove",
+                    "when": "view == env-managers && viewItem =~ /.*pythonBrokenEnvironment.*;remove;.*/"
+                },
                 {
                     "command": "python-envs.setEnv",
                     "group": "inline",
@@ -487,6 +501,16 @@
                     "group": "inline",
                     "when": "view == env-managers && viewItem =~ /.*pythonEnvironment.*/ && viewItem =~ /.*copied.*/"
                 },
+                {
+                    "command": "python-envs.copyEnvPath",
+                    "group": "inline",
+                    "when": "view == env-managers && viewItem =~ /.*pythonBrokenEnvironment.*/ && viewItem =~ /^((?!copied).)*$/"
+                },
+                {
+                    "command": "python-envs.copyEnvPathCopied",
+                    "group": "inline",
+                    "when": "view == env-managers && viewItem =~ /.*pythonBrokenEnvironment.*/ && viewItem =~ /.*copied.*/"
+                },
                 {
                     "command": "python-envs.uninstallPackage",
                     "group": "inline",
@@ -538,6 +562,11 @@
                     "command": "python-envs.uninstallPackage",
                     "group": "inline",
                     "when": "view == python-projects && viewItem == python-package"
+                },
+                {
+                    "command": "python-envs.revealEnvInManagerView",
+                    "group": "inline",
+                    "when": "view == python-projects && viewItem == python-env"
                 }
             ],
             "view/title": [

package.nls.json

@@ -43,6 +43,7 @@
     "python-envs.terminal.deactivate.title": "Deactivate Environment in Current Terminal",
     "python-envs.uninstallPackage.title": "Uninstall Package",
     "python-envs.revealProjectInExplorer.title": "Reveal Project in Explorer",
+    "python-envs.revealEnvInManagerView.title": "Reveal in Environment Managers View",
     "python-envs.runPetInTerminal.title": "Run Python Environment Tool (PET) in Terminal...",
     "python-envs.alwaysUseUv.description": "When set to true, uv will be used to manage all virtual environments if available. When set to false, uv will only manage virtual environments explicitly created by uv."
 }

src/api.ts

@@ -217,6 +217,13 @@ export interface PythonEnvironmentInfo {
      * Optional `group` for this environment. This is used to group environments in the Environment Manager UI.
      */
     readonly group?: string | EnvironmentGroupInfo;
+
+    /**
+     * Error message if the environment is broken or invalid.
+     * When set, indicates this environment has issues (e.g., broken symlinks, missing Python executable).
+     * The UI should display a warning indicator and show this message to help users diagnose and fix the issue.
+     */
+    readonly error?: string;
 }
 
 /**
@@ -922,7 +929,8 @@ export interface PythonProjectEnvironmentApi {
 }
 
 export interface PythonEnvironmentManagerApi
-    extends PythonEnvironmentManagerRegistrationApi,
+    extends
+        PythonEnvironmentManagerRegistrationApi,
         PythonEnvironmentItemApi,
         PythonEnvironmentManagementApi,
         PythonEnvironmentsApi,
@@ -987,7 +995,8 @@ export interface PythonPackageManagementApi {
 }
 
 export interface PythonPackageManagerApi
-    extends PythonPackageManagerRegistrationApi,
+    extends
+        PythonPackageManagerRegistrationApi,
         PythonPackageGetterApi,
         PythonPackageManagementApi,
         PythonPackageItemApi {}
@@ -1206,10 +1215,7 @@ export interface PythonBackgroundRunApi {
 }
 
 export interface PythonExecutionApi
-    extends PythonTerminalCreateApi,
-        PythonTerminalRunApi,
-        PythonTaskRunApi,
-        PythonBackgroundRunApi {}
+    extends PythonTerminalCreateApi, PythonTerminalRunApi, PythonTaskRunApi, PythonBackgroundRunApi {}
 
 /**
  * Event arguments for when the monitored `.env` files or any other sources change.
@@ -1258,7 +1264,8 @@ export interface PythonEnvironmentVariablesApi {
  * The API for interacting with Python environments, package managers, and projects.
  */
 export interface PythonEnvironmentApi
-    extends PythonEnvironmentManagerApi,
+    extends
+        PythonEnvironmentManagerApi,
         PythonPackageManagerApi,
         PythonProjectApi,
         PythonExecutionApi,

src/common/window.apis.ts

@@ -27,6 +27,8 @@ import {
     TerminalShellExecutionStartEvent,
     TerminalShellIntegrationChangeEvent,
     TextEditor,
+    TreeView,
+    TreeViewOptions,
     Uri,
     window,
     WindowState,
@@ -377,3 +379,7 @@ export function onDidChangeWindowState(
 ): Disposable {
     return window.onDidChangeWindowState(listener, thisArgs, disposables);
 }
+
+export function createTreeView<T>(viewId: string, options: TreeViewOptions<T>): TreeView<T> {
+    return window.createTreeView(viewId, options);
+}

src/extension.ts

@@ -35,6 +35,7 @@ import {
     refreshPackagesCommand,
     removeEnvironmentCommand,
     removePythonProject,
+    revealEnvInManagerView,
     revealProjectInExplorer,
     runAsTaskCommand,
     runInDedicatedTerminalCommand,
@@ -180,7 +181,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         }),
         commands.registerCommand('python-envs.viewLogs', () => outputChannel.show()),
         commands.registerCommand('python-envs.refreshAllManagers', async () => {
-            await Promise.all(envManagers.managers.map((m) => m.refresh(undefined)));
+            await window.withProgress({ location: { viewId: 'env-managers' } }, async () => {
+                await Promise.all(envManagers.managers.map((m) => m.refresh(undefined)));
+            });
         }),
         commands.registerCommand('python-envs.searchSettings', async () => {
             await openSearchSettings();
@@ -319,6 +322,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         commands.registerCommand('python-envs.revealProjectInExplorer', async (item) => {
             await revealProjectInExplorer(item);
         }),
+        commands.registerCommand('python-envs.revealEnvInManagerView', async (item) => {
+            await revealEnvInManagerView(item, managerView);
+        }),
         commands.registerCommand('python-envs.terminal.activate', async () => {
             const terminal = activeTerminal();
             if (terminal) {

src/features/envCommands.ts

@@ -1,15 +1,6 @@
 import * as fs from 'fs-extra';
 import * as path from 'path';
-import {
-    commands,
-    ProgressLocation,
-    QuickInputButtons,
-    TaskExecution,
-    TaskRevealKind,
-    Terminal,
-    Uri,
-    workspace,
-} from 'vscode';
+import { ProgressLocation, QuickInputButtons, TaskExecution, TaskRevealKind, Terminal, Uri, workspace } from 'vscode';
 import {
     CreateEnvironmentOptions,
     PythonEnvironment,
@@ -28,6 +19,7 @@ import {
 } from '../internal.api';
 import { removePythonProjectSetting, setEnvironmentManager, setPackageManager } from './settings/settingHelpers';
 
+import { executeCommand } from '../common/command.api';
 import { clipboardWriteText } from '../common/env.apis';
 import {} from '../common/errors/utils';
 import { Pickers } from '../common/localize';
@@ -52,6 +44,7 @@ import {
 import { runAsTask } from './execution/runAsTask';
 import { runInTerminal } from './terminal/runInTerminal';
 import { TerminalManager } from './terminal/terminalManager';
+import { EnvManagerView } from './views/envManagersView';
 import {
     EnvManagerTreeItem,
     EnvTreeItemKind,
@@ -469,7 +462,7 @@ export async function addPythonProjectCommand(
             'Open Folder',
         );
         if (r === 'Open Folder') {
-            await commands.executeCommand('vscode.openFolder');
+            await executeCommand('vscode.openFolder');
             return;
         }
     }
@@ -746,8 +739,21 @@ export async function copyPathToClipboard(item: unknown): Promise<void> {
 export async function revealProjectInExplorer(item: unknown): Promise<void> {
     if (item instanceof ProjectItem) {
         const projectUri = item.project.uri;
-        await commands.executeCommand('revealInExplorer', projectUri);
+        await executeCommand('revealInExplorer', projectUri);
     } else {
         traceVerbose(`Invalid context for reveal project in explorer: ${item}`);
     }
 }
+
+/**
+ * Focuses the Environment Managers view and reveals the given project environment.
+ */
+export async function revealEnvInManagerView(item: unknown, managerView: EnvManagerView): Promise<void> {
+    if (item instanceof ProjectEnvironment) {
+        await executeCommand('env-managers.focus');
+        await managerView.reveal(item.environment);
+        return;
+    }
+
+    traceVerbose(`Invalid context for reveal environment in manager view: ${item}`);
+}