Merge branch 'main' into copilot/fix-fd1747de-1940-4117-8fb2-d737e187c4de

Author: karthiknadig

.github/copilot-instructions.md

@@ -0,0 +1,139 @@
+# Python Environment Tools (PET) - AI Coding Agent Instructions
+
+## Project Overview
+
+This is a high-performance Rust-based tool for discovering Python environments and virtual environments. It operates as a JSONRPC server consumed by the VS Code Python extension to avoid spawning Python processes repeatedly.
+
+## Architecture
+
+### Core Concepts
+
+- **Locators**: Modular environment discovery components implementing the `Locator` trait (`crates/pet-core/src/lib.rs`)
+- **JSONRPC Server**: Main communication interface (`crates/pet/src/jsonrpc.rs`) with stdio/stdout protocol
+- **Environment Types**: 15+ supported Python installations (Conda, Poetry, PyEnv, Homebrew, Windows Store, etc.)
+- **Reporter Pattern**: Asynchronous environment discovery reporting via the `Reporter` trait
+
+### Key Architecture Files
+
+- `crates/pet/src/locators.rs` - Ordered locator creation and fallback identification logic
+- `crates/pet/src/find.rs` - Multi-threaded environment discovery coordination
+- `crates/pet-core/src/lib.rs` - Core traits and configuration structures
+- `docs/JSONRPC.md` - Complete API specification with TypeScript interfaces
+
+## Development Workflow
+
+### Building & Testing
+
+```bash
+# Standard build
+cargo build
+
+# Release build (optimized for performance)
+cargo build --release
+
+# Run tests with specific CI features
+cargo test --features ci
+cargo test --features ci-poetry-global
+
+# Run JSONRPC server
+./target/debug/pet server
+```
+
+### Feature-Gated Testing
+
+Tests use feature flags for different environments:
+
+- `ci` - General CI environment tests
+- `ci-jupyter-container` - Jupyter container-specific tests
+- `ci-homebrew-container` - Homebrew container tests
+- `ci-poetry-*` - Poetry-specific test variants
+
+### Locator Development Pattern
+
+When adding new environment types:
+
+1. **Create new crate**: `crates/pet-{name}/`
+2. **Implement Locator trait**: Key methods are `try_from()` (identification) and `find()` (discovery)
+3. **Add to locator chain**: Update `create_locators()` in `crates/pet/src/locators.rs` - ORDER MATTERS
+4. **Platform-specific**: Use `#[cfg(windows)]`, `#[cfg(unix)]`, `#[cfg(target_os = "macos")]`
+
+Example structure:
+
+```rust
+impl Locator for MyLocator {
+    fn get_kind(&self) -> LocatorKind { LocatorKind::MyType }
+    fn supported_categories(&self) -> Vec<PythonEnvironmentKind> { vec![PythonEnvironmentKind::MyType] }
+    fn try_from(&self, env: &PythonEnv) -> Option<PythonEnvironment> { /* identification logic */ }
+    fn find(&self, reporter: &dyn Reporter) { /* discovery logic */ }
+}
+```
+
+## Critical Patterns
+
+### Performance Principles (from `crates/pet/README.md`)
+
+1. **Avoid spawning processes** - Extract info from files/filesystem when possible
+2. **Report immediately** - Use Reporter pattern for async discovery
+3. **Complete information** - Gather all environment details in one pass, not incrementally
+
+### JSONRPC Communication Flow
+
+1. Client sends `configure` request (must be first)
+2. Client sends `refresh` request to discover environments
+3. Server sends `environment` notifications as discoveries happen
+4. Optional: `resolve` request for individual Python executables
+
+### Testing Verification Pattern
+
+Tests validate discovered environments using 4 verification methods:
+
+1. Spawn Python to verify `sys.prefix` and `sys.version`
+2. Use `try_from()` with executable to get same info
+3. Test symlink identification
+4. Use `resolve` method for consistency
+
+## Environment-Specific Notes
+
+### Conda Environments
+
+- Supports detection from history files and conda-meta directories
+- Manager detection via spawning conda executable in background threads
+- Complex prefix/name relationships for base vs named environments
+
+### Poetry Environments
+
+- Hash-based environment naming: `{project-name}-{hash}-py`
+- Project-specific virtual environments in configured cache directories
+- Configuration hierarchy: local poetry.toml → global config
+
+### Platform Differences
+
+- **Windows**: Registry + Windows Store detection, different path separators
+- **macOS**: Xcode Command Line Tools, python.org, Homebrew paths
+- **Linux**: Global system paths (`/usr/bin`, `/usr/local/bin`)
+
+## Common Gotchas
+
+- **Locator order matters** in `create_locators()` - more specific before generic
+- **Thread safety** - Heavy use of Arc/Mutex for concurrent discovery
+- **Feature flags** - Many tests only run with specific CI features enabled
+- **Path canonicalization** - Symlink resolution varies by platform
+- **Caching** - Optional cache directory for expensive operations (conda spawning)
+
+## Files to Read First
+
+1. `docs/JSONRPC.md` - Understanding the external API
+2. `crates/pet/src/locators.rs` - Core architecture patterns
+3. `crates/pet-core/src/lib.rs` - Essential traits and types
+4. `crates/pet/tests/ci_test.rs` - Comprehensive testing patterns
+
+
+## Scripts
+- Use `cargo fetch` to download all dependencies
+- Use `rustup component add clippy` to install Clippy linter
+- Use `cargo fmt --all` to format code in all packages
+- Use `cargo build` to build the project
+- Use `cargo test --all` to test all packages (this can take a few seconds)
+- Use `cargo test [TESTNAME]` to test a specific test
+- Use `cargo test -p [SPEC]` to test a specific package
+- Use `cargo test --all` to test all packages

.github/prompts/analyze.prompt.md

@@ -0,0 +1,38 @@
+---
+mode: agent
+description: Root cause analysis for a bug in the codebase.
+tools: ['codebase', 'editFiles', 'fetch', 'findTestFiles', 'githubRepo', 'search', 'searchResults', 'usages', 'vscodeAPI', 'github', 'get_file_contents', 'get_issue', 'get_issue_comments', 'list_issues', 'list_pull_requests', 'search_code', 'search_issues', 'memory', 'sequentialthinking', 'activePullRequest', 'websearch']
+---
+You are an expert in this codebase.
+
+Your goal is to analyze a bug or add the new feature, for this you first need to:
+* Understand the context of the bug or feature by reading the issue description and comments.
+* Ask for clarification from user only if the issue description is not clear.
+* Understand the codebase by reading the relevant instruction files and code.
+* If its a bug, then identify the root cause of the bug, and explain this to the user.
+* If just a number is provided by the user, assume it is an issue number and fetch the issue details.
+
+Based on your above understanding generate a summary of your analysis.
+Ensure the plan consists of a Markdown document that has the following sections:
+
+* Overview: A brief description of the bug/feature. If its a bug, then is this bydesign or a bug?
+* Root Cause: A detailed explanation of the root cause of the bug, including any relevant code snippets or references to the codebase. (only if it's a bug)
+* Requirements: A list of requirements to resolve the bug or add the new feature.
+* Additional Considerations: Mention any potential challenges or risks associated with the implementation.
+* Proposal: Can and should a solution be implemented? Is it a bug, or is this by design? What are the risks or challenges associated with a solution if it is a feature?
+
+Do not make any code edits, just generate a plan. Use thinking and reasoning skills to outline the steps needed to achieve the desired outcome.
+
+<reminder>
+MUST:
+- Read instruction file(s) before analyzing code
+- Understand codebase, issue and architecture thoroughly
+- Perform root cause analysis only if the issue is a bug
+- Never make any assumptions, always strive to be thorough and accurate
+- Avoid unnecessary repetition and verbosity
+- Be concise, but thorough.
+
+MUST NOT:
+- Make code changes
+- Mention all new or updated lines of code
+</reminder>

.github/prompts/explain.prompt.md

@@ -0,0 +1,40 @@
+---
+mode: agent
+description: Analyze the codebase and explain a feature/component in detail.
+tools: ['codebase', 'editFiles', 'fetch', 'findTestFiles', 'githubRepo', 'search', 'searchResults', 'usages', 'vscodeAPI', 'search_code', 'memory', 'sequentialthinking', 'websearch']
+---
+# Code Explanation Guide
+You are an expert in this codebase.
+Your task is to analyze the user requests and explain the feature/component in detail. Where possible use diagrams to depict the architecture and or flow.
+
+Start by first:
+* Understand what needs explaining.
+- Read instruction files for the relevant area
+- Examine code with appropriate tools
+- Understand the codebase by reading the relevant instruction files and code.
+- Identify design patterns and architectural decisions
+- Use available tools to gather information
+- Be thorough before presenting any explanation
+
+Based on your above understanding generate a markdown document that explains the feature/component in detail.
+Use thinking and reasoning skills when generating the explanation & ensure the document has the following sections:
+
+* Overview: Brief summary of the feature/component and its purpose.
+* Architecture: High-level architecture diagram (if applicable).
+* Key Components: List and describe key components involved.
+* Data Flow: Explain how data moves through the system.
+* Control Flow: Describe the control flow and how components interact.
+* Integration Points: Explain how this feature/component integrates with others.
+* Additional Considerations: Mention any potential challenges or risks associated with understanding or modifying this feature/component.
+Mention any other relevant information that would help in understanding the feature/component.
+
+
+<reminder>
+MUST:
+- Do not make any other code edits.
+- Read instruction file(s) before analyzing code
+- Understand codebase, issue and architecture thoroughly
+- Never make any assumptions, always strive to be thorough and accurate
+- Avoid unnecessary repetition and verbosity
+- Be concise, but thorough.
+</reminder>

.github/prompts/implement.prompt.md

@@ -0,0 +1,13 @@
+---
+mode: agent
+description: Executed after a plan has been created to implement a bug fix or feature request.
+tools: ['codebase', 'editFiles', 'fetch', 'findTestFiles', 'githubRepo', 'problems', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'github', 'get_file_contents', 'get_issue', 'get_issue_comments', 'list_issues', 'list_pull_requests', 'search_code', 'search_issues', 'memory', 'sequentialthinking', 'activePullRequest', 'copilotCodingAgent', 'websearch']
+---
+You are an expert in this codebase.
+Your task is to now implement the solution.
+
+<reminder>
+MUST:
+- Adhere to patterns and best practices of the project
+- Add required tests to ensure the fix works
+</reminder>

.github/prompts/plan.prompt.md

@@ -0,0 +1,40 @@
+---
+mode: agent
+description: Analyze a bug/issue in the codebase and report findings without making code changes.
+tools: ['codebase', 'editFiles', 'fetch', 'findTestFiles', 'githubRepo', 'search', 'searchResults', 'usages', 'vscodeAPI', 'github', 'get_file_contents', 'get_issue', 'get_issue_comments', 'list_issues', 'list_pull_requests', 'search_code', 'search_issues', 'memory', 'sequentialthinking', 'activePullRequest', 'websearch']
+---
+You are an expert in this codebase.
+
+Your goal is to prepare a detailed plan to fix the bug or add the new feature, for this you first need to:
+* Understand the context of the bug or feature by reading the issue description and comments.
+* Ask for clarification from user only if the issue description is not clear.
+* Understand the codebase by reading the relevant instruction files and code.
+* If its a bug, then identify the root cause of the bug, and explain this to the user.
+* If just a number is provided by the user, assume it is an issue number and fetch the issue details.
+
+Based on your above understanding generate a plan to fix the bug or add the new feature.
+Ensure the plan consists of a Markdown document that has the following sections:
+
+* Overview: A brief description of the bug/feature.
+* Problem: A detailed explanation of the root cause of the bug, including any relevant code snippets or references to the codebase. (only if it's a bug)
+* Solution: A brief summary of the solution including a list of requirements to resolve the bug or add the new feature.
+* Additional Considerations: Mention any potential challenges or risks associated with the implementation.
+* Implementation Steps: A detailed list of steps to implement the bug fix or new feature.
+Note: Limit information to what is necessary for developers and AI assistants to understand the implementation steps.
+Note: Adhere to architecture, development and testing patterns in instruction files
+
+Do not make any code edits, just generate a plan. Use thinking and reasoning skills to outline the steps needed to achieve the desired outcome.
+
+<reminder>
+MUST:
+- Understand codebase, issue and architecture thoroughly
+- Adhere to patterns and best practices of the project
+- Perform root cause analysis only if the issue is a bug
+- Never make any assumptions, always strive to be thorough and accurate
+- Avoid unnecessary repetition and verbosity
+- Be concise, but thorough.
+
+MUST NOT:
+- Make code changes
+- Mention all new or updated lines of code
+</reminder>

CodeQL.yml

@@ -0,0 +1,16 @@
+path_classifiers:
+  test:
+    # Note: use only forward slash / as a path separator.
+    # *  Matches any sequence of characters except a forward slash.
+    # ** Matches any sequence of characters, including a forward slash.
+    # This wildcard must either be surrounded by forward slash symbols, or used as the first segment of a path.
+    # It matches zero or more whole directory segments. There is no need to use a wildcard at the end of a directory path because all sub-directories are automatically matched.
+    # That is, /anything/ matches the anything directory and all its subdirectories.
+    # Always enclose the expression in double quotes if it includes *.
+    - "**/tests/**"
+
+  # The default behavior is to tag all files created during the
+  # build as `generated`. Results are hidden for generated code. You can tag
+  # further files as being generated by adding them to the `generated` section.
+  generated:
+    - target

crates/pet-conda/src/environments.rs

@@ -64,14 +64,14 @@ pub fn get_conda_environment_info(
         if conda_dir.exists() {
             trace!(
                 "Conda install folder {}, found, & will be used for the Conda Env: {}",
-                env_path.display(),
-                conda_dir.display()
+                conda_dir.display(),
+                env_path.display()
             );
         } else {
             warn!(
                 "Conda install folder {}, does not exist, hence will not be used for the Conda Env: {}",
-                env_path.display(),
-                conda_dir.display()
+                conda_dir.display(),
+                env_path.display()
             );
             conda_install_folder = None;
         }
@@ -136,6 +136,15 @@ pub fn get_conda_installation_used_to_create_conda_env(env_path: &Path) -> Optio
         if let Some(conda_dir) = get_conda_dir_from_cmd(line) {
             if is_conda_install(&conda_dir) {
                 return Some(conda_dir);
+            } else {
+                // Possible this is a directory such as `C:\Users\donja\miniconda3\Scripts`
+                // We try to remove `Scripts` or `bin` from the path in the `get_conda_dir_from_cmd`.
+                // However if there are other directories such as `condabin` or others we are not aware of, lets try.
+                if let Some(conda_dir) = conda_dir.parent() {
+                    if is_conda_install(conda_dir) {
+                        return Some(conda_dir.into());
+                    }
+                }
             }
         }
     }
@@ -233,6 +242,7 @@ fn get_conda_dir_from_cmd(cmd_line: String) -> Option<PathBuf> {
         if let Some(conda_dir) = cmd_line.file_name() {
             if conda_dir.to_string_lossy().to_lowercase() == "bin"
                 || conda_dir.to_string_lossy().to_lowercase() == "scripts"
+                || conda_dir.to_string_lossy().to_lowercase() == "condabin"
             {
                 if let Some(conda_dir) = cmd_line.parent() {
                     // Ensure the casing of the paths are correct.
@@ -285,7 +295,8 @@ fn is_conda_env_name_in_cmd(cmd_line: String, name: &str) -> bool {
     // # cmd: /Users/donjayamanne/miniconda3/bin/conda create -n conda1
     // # cmd_line: "# cmd: /usr/bin/conda create -p ./prefix-envs/.conda1 python=3.12 -y"
     // Look for "-n <name>" in the command line
-    cmd_line.contains(format!("-n {:?}", name).as_str())
+    cmd_line.contains(format!("-n {name}").as_str())
+        || cmd_line.contains(format!("--name {name}").as_str())
 }
 
 pub fn get_activation_command(
@@ -349,4 +360,23 @@ mod tests {
             PathBuf::from("/Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3")
         );
     }
+
+    #[test]
+    #[cfg(unix)]
+    fn verify_conda_env_name() {
+        let line = "# cmd: /Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3/lib/python3.10/site-packages/conda/__main__.py create --yes --name .conda python=3.12";
+        assert!(is_conda_env_name_in_cmd(line.to_string(), ".conda"));
+
+        let mut line = "# cmd: /Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3/lib/python3.10/site-packages/conda/__main__.py create --yes -n .conda python=3.12";
+        assert!(is_conda_env_name_in_cmd(line.to_string(), ".conda"));
+
+        line = "# cmd: /Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3/lib/python3.10/site-packages/conda/__main__.py create --yes --name .conda python=3.12";
+        assert!(!is_conda_env_name_in_cmd(line.to_string(), "base"));
+
+        line = "# cmd: /Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3/lib/python3.10/site-packages/conda/__main__.py create --yes -p .conda python=3.12";
+        assert!(!is_conda_env_name_in_cmd(line.to_string(), "base"));
+
+        line = "# cmd: /Users/donjayamanne/.pyenv/versions/mambaforge-22.11.1-3/lib/python3.10/site-packages/conda/__main__.py create --yes -p .conda python=3.12";
+        assert!(!is_conda_env_name_in_cmd(line.to_string(), ".conda"));
+    }
 }

crates/pet-conda/src/utils.rs

@@ -32,8 +32,9 @@ pub fn is_conda_install(path: &Path) -> bool {
 
 /// conda-meta must exist as this contains a mandatory `history` file.
 /// The root conda installation folder is also a conda environment (its the base environment).
+/// Exclude Pixi environments to avoid misidentifying them as conda environments.
 pub fn is_conda_env(path: &Path) -> bool {
-    path.join("conda-meta").is_dir()
+    path.join("conda-meta").is_dir() && !path.join("conda-meta").join("pixi").is_file()
 }
 
 /// Only used in tests, noop in production.