Implement Python environment management during install

- Created PythonEnvironment class for managing virtual environments
- Added support for uv, system Python, and skip options
- Added --python-manager CLI flag to install command
- Implemented interactive prompt for Python setup
- Added detection of existing virtual environments
- Updated config.yml schema to include python section
- Added comprehensive unit and integration tests
- Updated existing tests to work with new Python manager option

Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com>

Author: Copilot

src/deepwork/cli/install.py

@@ -2,14 +2,17 @@
 
 import shutil
 from pathlib import Path
+from typing import Optional
 
 import click
 from rich.console import Console
+from rich.prompt import Prompt
 
 from deepwork.core.adapters import AgentAdapter
 from deepwork.core.detector import PlatformDetector
 from deepwork.utils.fs import ensure_dir
 from deepwork.utils.git import is_git_repo
+from deepwork.utils.python_env import PythonEnvironment
 from deepwork.utils.yaml_utils import load_yaml, save_yaml
 
 console = Console()
@@ -226,6 +229,42 @@ def _create_rules_directory(project_path: Path) -> bool:
     return True
 
 
+def _prompt_python_setup(console: Console) -> dict:
+    """Prompt user for Python environment preferences.
+    
+    Args:
+        console: Rich console for output
+        
+    Returns:
+        Dictionary containing python configuration:
+            - manager: "uv" | "system" | "skip"
+            - version: Python version string
+            - venv_path: Path to virtual environment
+    """
+    console.print("\n[bold]Python Environment Setup[/bold]")
+    console.print("=" * 40)
+    console.print("\nHow should Python dependencies be managed?\n")
+
+    choices_display = [
+        ("1", "uv (Recommended)", "Creates isolated .venv with project-specific Python"),
+        ("2", "System Python", "Uses existing python3 from PATH"),
+        ("3", "Skip", "No Python environment setup"),
+    ]
+
+    for key, name, desc in choices_display:
+        console.print(f"  [{key}] {name}")
+        console.print(f"      {desc}\n")
+
+    choice = Prompt.ask("Choice", default="1", choices=["1", "2", "3"])
+
+    manager_map = {"1": "uv", "2": "system", "3": "skip"}
+    return {
+        "manager": manager_map[choice],
+        "version": "3.11",
+        "venv_path": ".venv"
+    }
+
+
 class DynamicChoice(click.Choice):
     """A Click Choice that gets its values dynamically from AgentAdapter."""
 
@@ -248,15 +287,20 @@ def __init__(self) -> None:
     default=".",
     help="Path to project directory (default: current directory)",
 )
-def install(platform: str | None, path: Path) -> None:
+@click.option(
+    "--python-manager",
+    type=click.Choice(["uv", "system", "skip"]),
+    help="Python environment manager (skips interactive prompt)",
+)
+def install(platform: str | None, path: Path, python_manager: str | None) -> None:
     """
     Install DeepWork in a project.
 
     Adds the specified AI platform to the project configuration and syncs
     commands for all configured platforms.
     """
     try:
-        _install_deepwork(platform, path)
+        _install_deepwork(platform, path, python_manager)
     except InstallError as e:
         console.print(f"[red]Error:[/red] {e}")
         raise click.Abort() from e
@@ -265,13 +309,14 @@ def install(platform: str | None, path: Path) -> None:
         raise
 
 
-def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
+def _install_deepwork(platform_name: str | None, project_path: Path, python_manager: str | None) -> None:
     """
     Install DeepWork in a project.
 
     Args:
         platform_name: Platform to install for (or None to auto-detect)
         project_path: Path to project directory
+        python_manager: Python environment manager choice (or None to prompt)
 
     Raises:
         InstallError: If installation fails
@@ -335,6 +380,32 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
                 platforms_to_add.append(adapter.name)
             detected_adapters = available_adapters
 
+    # Step 2b: Python environment setup
+    if python_manager:
+        python_config = {"manager": python_manager, "version": "3.11", "venv_path": ".venv"}
+    else:
+        # Check for existing venv
+        existing = PythonEnvironment.detect_existing(project_path)
+        if existing:
+            console.print(f"\n[green]→[/green] Found existing virtual environment: {existing.relative_to(project_path)}")
+            python_config = {"manager": "skip", "version": "3.11", "venv_path": str(existing.relative_to(project_path))}
+        else:
+            python_config = _prompt_python_setup(console)
+
+    # Create Python environment
+    if python_config["manager"] != "skip":
+        console.print(f"\n[yellow]→[/yellow] Setting up Python environment with {python_config['manager']}...")
+        env = PythonEnvironment(python_config)
+        try:
+            success = env.setup(project_path)
+            if success:
+                console.print("  [green]✓[/green] Virtual environment created")
+            else:
+                console.print("  [yellow]⚠[/yellow] Virtual environment setup returned False")
+        except RuntimeError as e:
+            console.print(f"  [red]✗[/red] Failed: {e}")
+            raise InstallError(f"Python environment setup failed: {e}") from e
+
     # Step 3: Create .deepwork/ directory structure
     console.print("[yellow]→[/yellow] Creating DeepWork directory structure...")
     deepwork_dir = project_path / ".deepwork"
@@ -393,6 +464,9 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
         else:
             console.print(f"  [dim]•[/dim] {adapter.display_name} already configured")
 
+    # Add python configuration
+    config_data["python"] = python_config
+
     save_yaml(config_file, config_data)
     console.print(f"  [green]✓[/green] Updated {config_file.relative_to(project_path)}")
 

src/deepwork/utils/python_env.py

@@ -0,0 +1,124 @@
+"""Python environment management utilities."""
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+class PythonEnvironment:
+    """Manages Python virtual environments."""
+
+    def __init__(self, config: dict):
+        """Initialize Python environment manager.
+        
+        Args:
+            config: Dictionary containing:
+                - manager: "uv" | "system" | "skip"
+                - version: Python version string (e.g., "3.11")
+                - venv_path: Path to virtual environment (e.g., ".venv")
+        """
+        self.manager = config.get("manager", "uv")
+        self.version = config.get("version", "3.11")
+        self.venv_path = Path(config.get("venv_path", ".venv"))
+
+    def setup(self, project_root: Path) -> bool:
+        """Create virtual environment based on configured manager.
+        
+        Args:
+            project_root: Path to the project root directory
+            
+        Returns:
+            True if setup succeeded, False otherwise
+            
+        Raises:
+            RuntimeError: If required tools are not available
+        """
+        if self.manager == "skip":
+            return True
+
+        venv_dir = project_root / self.venv_path
+
+        if self.manager == "uv":
+            return self._setup_with_uv(venv_dir)
+        elif self.manager == "system":
+            return self._setup_with_system(venv_dir)
+
+        return False
+
+    def _setup_with_uv(self, venv_dir: Path) -> bool:
+        """Create venv using uv.
+        
+        Args:
+            venv_dir: Path where virtual environment should be created
+            
+        Returns:
+            True if creation succeeded, False otherwise
+            
+        Raises:
+            RuntimeError: If uv is not found
+        """
+        if not shutil.which("uv"):
+            raise RuntimeError("uv not found. Install via: brew install uv")
+
+        cmd = ["uv", "venv", str(venv_dir), "--python", self.version]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        return result.returncode == 0
+
+    def _setup_with_system(self, venv_dir: Path) -> bool:
+        """Create venv using system Python.
+        
+        Args:
+            venv_dir: Path where virtual environment should be created
+            
+        Returns:
+            True if creation succeeded, False otherwise
+            
+        Raises:
+            RuntimeError: If Python is not found
+        """
+        python = shutil.which("python3") or shutil.which("python")
+        if not python:
+            raise RuntimeError("Python not found in PATH")
+
+        cmd = [python, "-m", "venv", str(venv_dir)]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        return result.returncode == 0
+
+    def install_package(self, package: str, project_root: Path) -> bool:
+        """Install a package into the virtual environment.
+        
+        Args:
+            package: Package name to install
+            project_root: Path to the project root directory
+            
+        Returns:
+            True if installation succeeded, False otherwise
+        """
+        venv_dir = project_root / self.venv_path
+
+        if self.manager == "uv":
+            cmd = ["uv", "pip", "install", package]
+        else:
+            pip = venv_dir / "bin" / "pip"
+            cmd = [str(pip), "install", package]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=project_root)
+        return result.returncode == 0
+
+    @staticmethod
+    def detect_existing(project_root: Path) -> Optional[Path]:
+        """Detect existing virtual environment.
+        
+        Args:
+            project_root: Path to the project root directory
+            
+        Returns:
+            Path to detected virtual environment, or None if not found
+        """
+        candidates = [".venv", "venv", ".virtualenv"]
+        for name in candidates:
+            venv_dir = project_root / name
+            if (venv_dir / "bin" / "python").exists():
+                return venv_dir
+        return None

tests/integration/test_install_flow.py

@@ -17,7 +17,7 @@ def test_install_with_claude(self, mock_claude_project: Path) -> None:
 
         result = runner.invoke(
             cli,
-            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            ["install", "--platform", "claude", "--path", str(mock_claude_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )
 
@@ -63,7 +63,7 @@ def test_install_with_auto_detect(self, mock_claude_project: Path) -> None:
         runner = CliRunner()
 
         result = runner.invoke(
-            cli, ["install", "--path", str(mock_claude_project)], catch_exceptions=False
+            cli, ["install", "--path", str(mock_claude_project), "--python-manager", "skip"], catch_exceptions=False
         )
 
         assert result.exit_code == 0
@@ -84,7 +84,7 @@ def test_install_defaults_to_claude_when_no_platform(self, mock_git_repo: Path)
         runner = CliRunner()
 
         result = runner.invoke(
-            cli, ["install", "--path", str(mock_git_repo)], catch_exceptions=False
+            cli, ["install", "--path", str(mock_git_repo), "--python-manager", "skip"], catch_exceptions=False
         )
 
         assert result.exit_code == 0
@@ -114,7 +114,7 @@ def test_install_with_multiple_platforms_auto_detect(
 
         result = runner.invoke(
             cli,
-            ["install", "--path", str(mock_multi_platform_project)],
+            ["install", "--path", str(mock_multi_platform_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )
 
@@ -162,15 +162,15 @@ def test_install_is_idempotent(self, mock_claude_project: Path) -> None:
         # First install
         result1 = runner.invoke(
             cli,
-            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            ["install", "--platform", "claude", "--path", str(mock_claude_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )
         assert result1.exit_code == 0
 
         # Second install
         result2 = runner.invoke(
             cli,
-            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            ["install", "--platform", "claude", "--path", str(mock_claude_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )
         assert result2.exit_code == 0
@@ -191,7 +191,7 @@ def test_install_creates_rules_directory(self, mock_claude_project: Path) -> Non
 
         result = runner.invoke(
             cli,
-            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            ["install", "--platform", "claude", "--path", str(mock_claude_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )
 
@@ -231,7 +231,7 @@ def test_install_preserves_existing_rules_directory(self, mock_claude_project: P
 
         result = runner.invoke(
             cli,
-            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            ["install", "--platform", "claude", "--path", str(mock_claude_project), "--python-manager", "skip"],
             catch_exceptions=False,
         )