Watch package changes through PackageWatcher instead of TerminaPacakageWatcher (#1698)

This pull request refactors and improves the package change detection
and watcher system for Python environments. It consolidates the logic
for watching package changes across all environment managers into a
single, manager-agnostic watcher registration, and removes redundant or
manager-specific watcher code. The new system ensures that package
changes are detected and handled consistently, regardless of environment
type or package manager.

Fixes #1683 

**Core improvements to package watcher system:**

* A new `registerPackageWatchers` function is introduced in
`packageWatcher.ts`, which registers package watchers for all active
environments, sharing watchers when environments are active in multiple
scopes and cleaning up watchers when no longer needed. This replaces the
old per-manager watcher registration.
([src/managers/common/packageWatcher.tsL2-R11](diffhunk://#diff-db307f917634197b286344124fab7702aa1c37601df0c09bceba8b6d1cd76cd3L2-R11),
F89a1842L51R51)
* The watcher registration is now called once during extension
activation, rather than per environment manager, ensuring all active
environments are covered.
[[1]](diffhunk://#diff-04bba6a35cad1c794cbbe677678a51de13441b7a6ee8592b7b50be1f05c6f626R673-R674)
[[2]](diffhunk://#diff-04bba6a35cad1c794cbbe677678a51de13441b7a6ee8592b7b50be1f05c6f626L684-L688)
* The watcher logic is updated to better handle watcher sharing and
disposal, and to use improved glob patterns for `.dist-info`
directories, catching more package changes. (F89a1842L18R18,
F89a1842L43R43)

**Cleanup and removal of legacy code:**

* The old `terminalPackageWatcher.ts` and its related imports and
registration are removed, as its functionality is now covered by the new
watcher system.
[[1]](diffhunk://#diff-04bba6a35cad1c794cbbe677678a51de13441b7a6ee8592b7b50be1f05c6f626L89)
[[2]](diffhunk://#diff-04bba6a35cad1c794cbbe677678a51de13441b7a6ee8592b7b50be1f05c6f626L684-L688)
[[3]](diffhunk://#diff-9b9f96660a5ea04265c5ed7f91dba539d24dc06469c0feed8e3af541aa7d1321L1-L111)
* Manager-specific watcher registration code is removed from
`builtin/main.ts` and `poetry/main.ts`, further consolidating watcher
logic.
[[1]](diffhunk://#diff-450a068335039323c00b342cbfbff615ecf1cda7bd9d73aaed6b8e13d2d9d7f5L7)
[[2]](diffhunk://#diff-450a068335039323c00b342cbfbff615ecf1cda7bd9d73aaed6b8e13d2d9d7f5L44-L48)
[[3]](diffhunk://#diff-27854fc91d92524ea1d6cecfec07dcb12f64204246b5d45097156ddc3a1867ecL7)
[[4]](diffhunk://#diff-27854fc91d92524ea1d6cecfec07dcb12f64204246b5d45097156ddc3a1867ecL28)

**API and test updates:**

* The `InternalPackageManager` class now exposes a
`getPackageWatchTargets` method to allow custom watch targets per
package manager.
* Tests are updated to use the new watcher registration API.
[[1]](diffhunk://#diff-960d3ebbd27add9587b7da36c8ce1af3836525d17909b0e8f8fb01cf293f7ac3L7-R10)
[[2]](diffhunk://#diff-960d3ebbd27add9587b7da36c8ce1af3836525d17909b0e8f8fb01cf293f7ac3L87-L95)

These changes improve maintainability, reliability, and coverage of
package change detection across all Python environments managed by the
extension.

---------

Copilot-Session: a7de2667-ab70-47de-a8fd-5b00953e14f7

Author: edvilme

docs/startup-flow.md

@@ -91,7 +91,7 @@ All three trigger `initialize()` lazily (once-only, guarded by `_initialized` de
 ---
 
 POST-INIT:
-1. register terminal package watcher
+1. register package watchers for workspace-selected and terminal-activated environments
 2. register settings change listener (`registerInterpreterSettingsChangeListener`) — re-runs priority chain if settings change
 3.  initialize terminal manager
 4.  send telemetry (manager selection, project structure, discovery summary)

src/extension.ts

@@ -86,26 +86,26 @@ import { cleanupStartupScripts } from './features/terminal/shellStartupSetupHand
 import { TerminalActivationImpl } from './features/terminal/terminalActivationState';
 import { TerminalEnvVarInjector } from './features/terminal/terminalEnvVarInjector';
 import { TerminalManager, TerminalManagerImpl } from './features/terminal/terminalManager';
-import { registerTerminalPackageWatcher } from './features/terminal/terminalPackageWatcher';
 import { getEnvironmentForTerminal } from './features/terminal/utils';
 import { openSearchSettings } from './features/views/envManagerSearch';
 import { EnvManagerView } from './features/views/envManagersView';
 import { ProjectView } from './features/views/projectView';
 import { PythonStatusBarImpl } from './features/views/pythonStatusBar';
 import { updateViewsAndStatus } from './features/views/revealHandler';
 import { TemporaryStateManager } from './features/views/temporaryStateManager';
-import { ProjectItem, PythonEnvTreeItem } from './features/views/treeViewItems';
+import { PythonEnvTreeItem } from './features/views/treeViewItems';
 import { collectEnvironmentInfo, getEnvManagerAndPackageManagerConfigLevels, runPetInTerminalImpl } from './helpers';
 import { EnvironmentManagers, ProjectCreators, PythonProjectManager } from './internal.api';
-import { registerSystemPythonFeatures } from './managers/builtin/main';
 import { registerInlineScriptFeatures } from './managers/builtin/inlineScript/main';
+import { registerSystemPythonFeatures } from './managers/builtin/main';
 import { SysPythonManager } from './managers/builtin/sysPythonManager';
 import {
     createNativePythonFinder,
     getNativePythonToolsPathAndSource,
     getNativePythonToolsVersion,
     NativePythonFinder,
 } from './managers/common/nativePythonFinder';
+import { registerPackageWatchers } from './managers/common/packageWatcher';
 import { IDisposable } from './managers/common/types';
 import { registerCondaFeatures } from './managers/conda/main';
 import { registerPipenvFeatures } from './managers/pipenv/main';
@@ -364,17 +364,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             });
         }),
         commands.registerCommand('python-envs.removePythonProject', async (item) => {
-            // Clear environment association before removing project
-            if (item instanceof ProjectItem) {
-                const uri = item.project.uri;
-                const manager = envManagers.getEnvironmentManager(uri);
-                if (manager) {
-                    manager.set(uri, undefined);
-                } else {
-                    traceError(`No environment manager found for ${uri.fsPath}`);
-                }
-            }
-            await removePythonProject(item, projectManager);
+            await removePythonProject(item, projectManager, envManagers);
         }),
         commands.registerCommand('python-envs.clearCache', async () => {
             await clearPersistentState();
@@ -672,6 +662,8 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 safeRegister('shellStartupVars', shellStartupVarsMgr.initialize()),
             ]);
 
+            context.subscriptions.push(registerPackageWatchers(envManagers, terminalActivation, outputChannel));
+
             failureStage = 'envSelection';
             stageWatch.reset();
             await applyInitialEnvironmentSelection(
@@ -683,11 +675,6 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 globalScopeDeferredRef,
             );
 
-            // Register manager-agnostic terminal watcher for package-modifying commands
-            failureStage = 'terminalWatcher';
-            stageWatch.reset();
-            registerTerminalPackageWatcher(api, terminalActivation, outputChannel, context.subscriptions);
-
             // Register listener for interpreter settings changes for interpreter re-selection
             failureStage = 'settingsListener';
             stageWatch.reset();

src/features/envCommands.ts

@@ -652,7 +652,12 @@ export async function addPythonProjectCommand(
     }
 }
 
-export async function removePythonProject(item: ProjectItem, wm: PythonProjectManager): Promise<void> {
+export async function removePythonProject(
+    item: ProjectItem,
+    wm: PythonProjectManager,
+    em: EnvironmentManagers,
+): Promise<void> {
+    await em.setEnvironment(item.project.uri, undefined);
     await removePythonProjectSetting([{ project: item.project }]);
     wm.remove(item.project);
 }

src/features/terminal/terminalPackageWatcher.ts

@@ -1,5 +1,5 @@
 import type { Pep440Version } from '@renovatebot/pep440';
-import { CancellationError, Disposable, Event, LogOutputChannel, MarkdownString, Uri } from 'vscode';
+import { CancellationError, Disposable, Event, LogOutputChannel, MarkdownString, RelativePattern, Uri } from 'vscode';
 import {
     CreateEnvironmentOptions,
     CreateEnvironmentScope,
@@ -380,6 +380,10 @@ export class InternalPackageManager implements PackageManager {
         return this.manager.getPackages(environment, options);
     }
 
+    getPackageWatchTargets(environment: PythonEnvironment): RelativePattern[] {
+        return this.manager.getPackageWatchTargets?.(environment) ?? [];
+    }
+
     onDidChangePackages(handler: (e: DidChangePackagesEventArgs) => void): Disposable {
         return this.manager.onDidChangePackages ? this.manager.onDidChangePackages(handler) : new Disposable(() => {});
     }

src/internal.api.ts

@@ -4,7 +4,6 @@ import { createSimpleDebounce } from '../../common/utils/debounce';
 import { createFileSystemWatcher, onDidDeleteFiles } from '../../common/workspace.apis';
 import { getPythonApi } from '../../features/pythonApi';
 import { NativePythonFinder } from '../common/nativePythonFinder';
-import { registerPackageWatcherForManager } from '../common/packageWatcher';
 import { PipPackageManager } from './pipPackageManager';
 import { SysPythonManager } from './sysPythonManager';
 import { VenvManager } from './venvManager';
@@ -41,9 +40,4 @@ export async function registerSystemPythonFeatures(
             venvDebouncedRefresh.trigger();
         }),
     );
-
-    disposables.push(
-        registerPackageWatcherForManager(envManager, pkgManager, log),
-        registerPackageWatcherForManager(venvManager, pkgManager, log),
-    );
 }

src/managers/builtin/main.ts

@@ -127,7 +127,11 @@ export class PipPackageManager implements PackageManager, Disposable {
     async getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined> {
         if (options?.skipCache || !this.packages.has(environment.envId.id)) {
             const data = await refreshPipPackages(environment, this.log);
-            const packages = (data ?? []).map((pkg) => this.api.createPackageItem(pkg, environment, this));
+            if (data === undefined) {
+                return this.packages.get(environment.envId.id);
+            }
+
+            const packages = data.map((pkg) => this.api.createPackageItem(pkg, environment, this));
             this.packages.set(environment.envId.id, packages);
             return packages;
         }