Implement automatic package list refresh when site-packages change

[Copilot]

Overview

This PR implements automatic package list refresh when packages are installed or uninstalled (including from the command line) by monitoring the site-packages directory for changes. This enhancement provides a seamless user experience by eliminating the need for manual package list refreshes.

Problem Statement

Previously, users had to manually refresh package lists in the VS Code Python Environments extension after installing or uninstalling packages via command line tools like pip install or conda install. This created a disconnect between the actual package state and what was displayed in the extension.

Solution

The implementation introduces a file system watcher service that:

1. Monitors site-packages directories for all Python environments
2. Automatically triggers package refresh when changes are detected
3. Works across all environment types (venv, conda, system Python, poetry, pyenv)
4. Supports all platforms (Windows, macOS, Linux)

Key Features

🔍 Smart Path Resolution

• Automatically resolves site-packages paths using environment sysPrefix
• Handles platform differences:
  • Windows: {sysPrefix}/Lib/site-packages
  • Unix/Linux/macOS: {sysPrefix}/lib/python*/site-packages
  • Conda: {sysPrefix}/site-packages

🔄 Lifecycle Management

• Watchers are automatically created when environments are added
• Watchers are properly disposed when environments are removed
• Service integrates seamlessly with existing environment manager events

⚡ Performance Optimized

• Asynchronous package refreshes to avoid blocking UI
• Debounced file system events to prevent excessive refresh calls
• Minimal overhead with efficient VS Code file system watchers

🛡️ Robust Error Handling

• Graceful handling of environments without valid sysPrefix
• Fallback behavior when site-packages directories cannot be found
• Comprehensive logging for debugging

Implementation Details

New Components

1. SitePackagesWatcherService - Main service managing file system watchers
2. sitePackagesUtils.ts - Utility functions for path resolution and validation
3. Integration in extension.ts - Service initialization during extension activation

Code Structure

// Service automatically initializes watchers for existing environments
const sitePackagesWatcher = new SitePackagesWatcherService(envManagers);
context.subscriptions.push(sitePackagesWatcher);

// Utility function resolves site-packages path for any environment
const sitePackagesUri = await resolveSitePackagesPath(environment);

Testing

• ✅ Unit tests for site-packages path resolution across platforms
• ✅ Unit tests for directory validation logic
• ✅ Integration tests for service initialization and disposal
• ✅ Test coverage for error conditions and edge cases

Example Usage

After this change, the following workflow now works seamlessly:

1. User opens VS Code with Python Environments extension
2. User runs pip install requests in terminal
3. Package list automatically updates without manual refresh
4. New package appears in the environments view immediately

Backwards Compatibility

This change is fully backwards compatible:

• No breaking changes to existing APIs
• No changes to user-facing commands or settings
• Purely additive functionality that enhances existing features

Files Changed

• Added: src/features/packageWatcher/sitePackagesWatcherService.ts
• Added: src/features/packageWatcher/sitePackagesUtils.ts
• Added: src/features/packageWatcher/index.ts
• Modified: src/extension.ts (added service initialization)
• Added: src/test/features/packageWatcher/sitePackagesUtils.unit.test.ts
• Added: src/test/features/packageWatcher/sitePackagesWatcherService.unit.test.ts
• Added: docs/automatic-package-refresh.md

Validation

The implementation has been tested to ensure:

• ✅ Extension builds and compiles successfully
• ✅ All existing unit tests continue to pass
• ✅ New functionality is covered by comprehensive tests
• ✅ Service properly disposes resources on extension deactivation
• ✅ File system watchers are efficiently managed

This enhancement significantly improves the developer experience by providing real-time package list updates that stay in sync with the actual environment state.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[eleanorjboyd]

this solution seems a bit complex with getting possible paths to check. Instead can you make it so every environment has a path called "packageFolder" that needs to be set when the environment is created

[Copilot]

this solution seems a bit complex with getting possible paths to check. Instead can you make it so every environment has a path called "packageFolder" that needs to be set when the environment is crea...

I've simplified the implementation as requested. The solution now uses a packageFolder property on each environment instead of complex path resolution logic.

Key changes made:

• Added packageFolder?: Uri property to PythonEnvironmentInfo interface
• Updated environment managers (venv, conda) to set packageFolder when creating environments
• Simplified SitePackagesWatcherService to use packageFolder directly instead of resolving paths at runtime
• Replaced complex platform-specific path discovery with simple utility function resolvePackageFolderFromSysPrefix()
• Updated tests and documentation

This approach is much cleaner as it moves the responsibility of knowing the package directory to the environment managers who create the environments, eliminating runtime path guessing.

Implemented in commit 3105593.