devs-cli 0.1.0__py3-none-any.whl

devs/config.py

@@ -0,0 +1,44 @@
+"""Configuration management for devs package."""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from devs_common.config import BaseConfig
+
+
+class Config(BaseConfig):
+    """Configuration settings for devs CLI."""
+    
+    # Default settings
+    PROJECT_PREFIX = "dev"
+    WORKSPACES_DIR = Path.home() / ".devs" / "workspaces"
+    CLAUDE_CONFIG_DIR = Path.home() / ".devs" / "claudeconfig"
+    
+    def __init__(self) -> None:
+        """Initialize configuration with environment variable overrides."""
+        super().__init__()
+        
+        # CLI-specific configuration
+        claude_config_env = os.getenv("DEVS_CLAUDE_CONFIG_DIR")
+        if claude_config_env:
+            self.claude_config_dir = Path(claude_config_env)
+        else:
+            self.claude_config_dir = self.CLAUDE_CONFIG_DIR
+    
+    def get_default_workspaces_dir(self) -> Path:
+        """Get default workspaces directory for CLI package."""
+        return self.WORKSPACES_DIR
+    
+    def get_default_project_prefix(self) -> str:
+        """Get default project prefix for CLI package."""
+        return self.PROJECT_PREFIX
+    
+    def ensure_directories(self) -> None:
+        """Ensure required directories exist."""
+        super().ensure_directories()
+        self.claude_config_dir.mkdir(parents=True, exist_ok=True)
+
+
+# Global config instance
+config = Config()

devs/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core functionality for devcontainer management."""
+
+# Import from common package
+from devs_common.core.project import Project, ProjectInfo
+from devs_common.core.workspace import WorkspaceManager
+from devs_common.core.container import ContainerManager, ContainerInfo
+
+__all__ = ["Project", "ProjectInfo", "WorkspaceManager", "ContainerManager", "ContainerInfo"]

devs/core/integration.py

@@ -0,0 +1,290 @@
+"""VS Code and external tool integrations."""
+
+import subprocess
+import time
+from pathlib import Path
+from typing import List
+
+from rich.console import Console
+
+from ..exceptions import VSCodeError, DependencyError
+from devs_common.core.project import Project
+from devs_common.utils.devcontainer import prepare_devcontainer_environment
+
+console = Console()
+
+
+class VSCodeIntegration:
+    """Handles VS Code integration and launching."""
+    
+    def __init__(self, project: Project) -> None:
+        """Initialize VS Code integration.
+        
+        Args:
+            project: Project instance
+        """
+        self.project = project
+        self._check_vscode_cli()
+    
+    def _check_vscode_cli(self) -> None:
+        """Check if VS Code CLI is available.
+        
+        Raises:
+            DependencyError: If code command is not found
+        """
+        try:
+            result = subprocess.run(
+                ['code', '--version'],
+                capture_output=True,
+                text=True,
+                check=False
+            )
+            if result.returncode != 0:
+                raise DependencyError(
+                    "VS Code 'code' command not found. Make sure VS Code is installed "
+                    "and the 'code' command is available in your PATH."
+                )
+        except FileNotFoundError:
+            raise DependencyError(
+                "VS Code 'code' command not found. Make sure VS Code is installed "
+                "and the 'code' command is available in your PATH."
+            )
+    
+    def generate_devcontainer_uri(self, workspace_dir: Path, dev_name: str, live: bool = False, attach_to_existing: bool = True) -> str:
+        """Generate VS Code devcontainer URI.
+        
+        Args:
+            workspace_dir: Workspace directory path
+            dev_name: Development environment name
+            live: Whether to use live mode (mount current directory)
+            attach_to_existing: Whether to attach to existing container (vs create new one)
+            
+        Returns:
+            VS Code devcontainer URI
+        """
+        if attach_to_existing:
+            # Generate container name to attach to
+            container_name = self.project.get_container_name(dev_name)
+            # Use attached-container URI format to connect to existing container
+            # Encode container name for URI
+            container_hex = container_name.encode('utf-8').hex()
+            
+            # Generate workspace path inside container
+            workspace_name = workspace_dir.name if live else self.project.get_workspace_name(dev_name)
+            vscode_uri = f"vscode-remote://attached-container+{container_hex}/workspaces/{workspace_name}"
+        else:
+            # Original behavior: create new container from devcontainer.json
+            # Convert workspace path to hex for VS Code URI
+            workspace_hex = workspace_dir.as_posix().encode('utf-8').hex()
+            
+            # Generate workspace name inside container
+            # IMPORTANT: In live mode, we must use the actual host folder name (e.g. "workstuff")
+            # because devcontainer CLI mounts the host directory directly, preserving its name.
+            # VS Code needs to connect to /workspaces/<host-folder-name>, not our constructed name.
+            workspace_name = workspace_dir.name if live else self.project.get_workspace_name(dev_name)
+            
+            # Build VS Code devcontainer URI
+            vscode_uri = f"vscode-remote://dev-container+{workspace_hex}/workspaces/{workspace_name}"
+        
+        return vscode_uri
+    
+    def launch_devcontainer(
+        self, 
+        workspace_dir: Path, 
+        dev_name: str,
+        new_window: bool = True,
+        live: bool = False
+    ) -> bool:
+        """Launch a devcontainer in VS Code.
+        
+        Args:
+            workspace_dir: Workspace directory path
+            dev_name: Development environment name 
+            new_window: Whether to open in a new window
+            live: Whether to use live mode (mount current directory)
+            
+        Returns:
+            True if VS Code launched successfully
+            
+        Raises:
+            VSCodeError: If VS Code launch fails
+        """
+        try:
+            # Always attach to existing container (since we ensure it's running in CLI)
+            vscode_uri = self.generate_devcontainer_uri(workspace_dir, dev_name, live, attach_to_existing=True)
+            
+            console.print(f"   🚀 Opening VS Code for: {dev_name}")
+            
+            # Build VS Code command
+            cmd = ['code']
+            
+            if new_window:
+                cmd.append('--new-window')
+            
+            cmd.extend(['--folder-uri', vscode_uri])
+            
+            # Set environment variables using shared function
+            container_workspace_name = self.project.get_workspace_name(dev_name)
+            env = prepare_devcontainer_environment(
+                dev_name=dev_name,
+                project_name=self.project.info.name,
+                workspace_folder=workspace_dir,
+                container_workspace_name=container_workspace_name,
+                git_remote_url=self.project.info.git_remote_url,
+                debug=False,  # VS Code launch doesn't need debug mode
+                live=live
+            )
+            
+            # Launch VS Code in background
+            process = subprocess.Popen(
+                cmd,
+                env=env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True
+            )
+            
+            # Give it a moment to start
+            time.sleep(1)
+            
+            # Check if process is still running (not immediately failed)
+            if process.poll() is not None and process.returncode != 0:
+                raise VSCodeError(f"VS Code process exited with code {process.returncode}")
+            
+            console.print(f"   ✅ Launched VS Code for: {dev_name}")
+            return True
+            
+        except subprocess.SubprocessError as e:
+            raise VSCodeError(f"Failed to launch VS Code for {dev_name}: {e}")
+    
+    def launch_multiple_devcontainers(
+        self, 
+        workspace_dirs: List[Path], 
+        dev_names: List[str],
+        delay_between_windows: float = 2.0,
+        live: bool = False
+    ) -> int:
+        """Launch multiple devcontainers in separate VS Code windows.
+        
+        Args:
+            workspace_dirs: List of workspace directory paths
+            dev_names: List of development environment names
+            delay_between_windows: Delay between opening windows (seconds)
+            live: Whether to use live mode (mount current directory)
+            
+        Returns:
+            Number of successfully launched windows
+        """
+        if len(workspace_dirs) != len(dev_names):
+            raise VSCodeError("Workspace directories and dev names lists must have same length")
+        
+        console.print(f"📂 Opening {len(dev_names)} devcontainers in VS Code for project: {self.project.info.name}")
+        
+        success_count = 0
+        
+        for workspace_dir, dev_name in zip(workspace_dirs, dev_names):
+            try:
+                if self.launch_devcontainer(workspace_dir, dev_name, new_window=True, live=live):
+                    success_count += 1
+                
+                # Add delay between windows to ensure they open separately
+                if delay_between_windows > 0:
+                    time.sleep(delay_between_windows)
+                    
+            except VSCodeError as e:
+                console.print(f"   ❌ Failed to launch {dev_name}: {e}")
+                continue
+        
+        if success_count > 0:
+            console.print("")
+            console.print(f"💡 VS Code windows should open shortly with titles: '<dev-name> - {self.project.info.directory.name}'")
+        
+        return success_count
+    
+class ExternalToolIntegration:
+    """Handles integration with external development tools."""
+    
+    def __init__(self, project: Project) -> None:
+        """Initialize external tool integration.
+        
+        Args:
+            project: Project instance
+        """
+        self.project = project
+    
+    def check_dependencies(self) -> dict:
+        """Check availability of external dependencies.
+        
+        Returns:
+            Dictionary mapping tool names to availability status
+        """
+        tools = {
+            'docker': ['docker', '--version'],
+            'devcontainer': ['devcontainer', '--version'],
+            'code': ['code', '--version'],
+            'git': ['git', '--version'],
+        }
+        
+        status = {}
+        
+        for tool_name, cmd in tools.items():
+            try:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    check=False
+                )
+                status[tool_name] = {
+                    'available': result.returncode == 0,
+                    'version': result.stdout.strip() if result.returncode == 0 else None,
+                    'error': result.stderr.strip() if result.returncode != 0 else None
+                }
+            except FileNotFoundError:
+                status[tool_name] = {
+                    'available': False,
+                    'version': None,
+                    'error': 'Command not found'
+                }
+        
+        return status
+    
+    def print_dependency_status(self) -> None:
+        """Print status of all dependencies."""
+        status = self.check_dependencies()
+        
+        console.print("\n🔧 Dependency Status:")
+        console.print("─" * 40)
+        
+        for tool_name, info in status.items():
+            if info['available']:
+                console.print(f"   ✅ {tool_name}: {info['version']}")
+            else:
+                console.print(f"   ❌ {tool_name}: {info['error']}")
+        
+        # Check for missing critical dependencies
+        critical_tools = ['docker', 'devcontainer']
+        missing_critical = [
+            tool for tool in critical_tools 
+            if not status.get(tool, {}).get('available', False)
+        ]
+        
+        if missing_critical:
+            console.print(f"\n⚠️  Missing critical dependencies: {', '.join(missing_critical)}")
+            console.print("   Please install missing tools before using devs.")
+        else:
+            console.print("\n✅ All critical dependencies are available.")
+    
+    def get_missing_dependencies(self) -> List[str]:
+        """Get list of missing critical dependencies.
+        
+        Returns:
+            List of missing tool names
+        """
+        status = self.check_dependencies()
+        critical_tools = ['docker', 'devcontainer']
+        
+        return [
+            tool for tool in critical_tools
+            if not status.get(tool, {}).get('available', False)
+        ]

devs/exceptions.py

@@ -0,0 +1,24 @@
+"""Custom exceptions for devs package."""
+
+# Import from common package for compatibility
+from devs_common.exceptions import (
+    DevsError,
+    ProjectNotFoundError,
+    DevcontainerConfigError,
+    ContainerError,
+    DockerError,
+    WorkspaceError,
+    VSCodeError,
+    DependencyError,
+)
+
+__all__ = [
+    "DevsError",
+    "ProjectNotFoundError", 
+    "DevcontainerConfigError",
+    "ContainerError",
+    "DockerError",
+    "WorkspaceError",
+    "VSCodeError",
+    "DependencyError",
+]

devs/utils/__init__.py

@@ -0,0 +1,28 @@
+"""Utility modules for devcontainer management."""
+
+# Import from common package for compatibility  
+from devs_common.utils import (
+    copy_file_list,
+    copy_directory_tree,
+    safe_remove_directory,
+    ensure_directory_exists,
+    get_directory_size,
+    is_directory_empty,
+    get_tracked_files,
+    is_git_repository,
+    DockerClient,
+    DevContainerCLI,
+)
+
+__all__ = [
+    "copy_file_list",
+    "copy_directory_tree",
+    "safe_remove_directory", 
+    "ensure_directory_exists",
+    "get_directory_size",
+    "is_directory_empty",
+    "get_tracked_files",
+    "is_git_repository",
+    "DockerClient",
+    "DevContainerCLI",
+]

devs_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: devs-cli
+Version: 0.1.0
+Summary: DevContainer Management Tool - Manage multiple named devcontainers for any project
+Author: Dan Lester
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ideonate/devs
+Project-URL: Repository, https://github.com/ideonate/devs
+Project-URL: Issues, https://github.com/ideonate/devs/issues
+Project-URL: Documentation, https://github.com/ideonate/devs/tree/main/packages/cli
+Keywords: devcontainer,docker,vscode,development
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: devs-common>=0.1.0
+Requires-Dist: rich>=12.0.0
+Requires-Dist: pathspec>=0.10.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# devs - DevContainer Management Tool
+
+A Python command-line tool that simplifies managing multiple named devcontainers for any project.
+
+## Features
+
+- **Multiple Named Containers**: Start multiple devcontainers with custom names (e.g., "sally", "bob", "charlie")
+- **VS Code Integration**: Open containers in separate VS Code windows with clear titles
+- **Project Isolation**: Containers are prefixed with git repository names (org-repo format)
+- **Environment Variable Management**: Layered DEVS.yml configuration with user-specific overrides
+- **Shared Authentication**: Claude credentials are shared between containers for the same project
+- **Cross-Platform**: Works on any project with devcontainer configuration
+
+## Installation
+
+```bash
+pip install devs
+```
+
+## Usage
+
+```bash
+# Start development environments
+devs start frontend backend
+
+# Open both in VS Code (separate windows)
+devs vscode frontend backend
+
+# Work in a specific container
+devs shell frontend
+
+# Run Claude in a container
+devs claude frontend "Summarize this codebase"
+
+# Run tests in a container
+devs runtests frontend
+
+# Environment variables support
+devs start frontend --env DEBUG=true --env API_URL=http://localhost:3000
+devs claude frontend "Fix the tests" --env NODE_ENV=test
+
+# Set up Claude authentication (once per host)
+devs claude-auth
+# Or with API key
+devs claude-auth --api-key <YOUR_API_KEY>
+
+# Clean up when done
+devs stop frontend backend
+
+# List active containers
+devs list
+```
+
+## Configuration
+
+### Environment Variables
+
+devs supports layered environment variable configuration through DEVS.yml files:
+
+**Priority order (highest to lowest):**
+1. CLI `--env` flags
+2. `~/.devs/envs/{org-repo}/DEVS.yml` (user-specific project overrides)
+3. `~/.devs/envs/default/DEVS.yml` (user defaults)
+4. `{project-root}/DEVS.yml` (repository configuration)
+
+**Example DEVS.yml in your project:**
+```yaml
+env_vars:
+  default:
+    NODE_ENV: development
+    API_URL: https://api.example.com
+    DEBUG: "false"
+  
+  frontend:  # Container-specific overrides
+    DEBUG: "true"
+    FRONTEND_PORT: "3000"
+    
+  backend:
+    NODE_ENV: production
+    API_URL: https://prod-api.example.com
+```
+
+**User-specific configuration:**
+```bash
+# Global user defaults
+mkdir -p ~/.devs/envs/default
+echo 'env_vars:
+  default:
+    GLOBAL_SETTING: "user_preference"
+    MY_SECRET: "user_secret"' > ~/.devs/envs/default/DEVS.yml
+
+# Project-specific overrides (org-repo format)
+mkdir -p ~/.devs/envs/myorg-myproject
+echo 'env_vars:
+  frontend:
+    DEBUG: "true"
+    LOCAL_SECRET: "dev_secret"' > ~/.devs/envs/myorg-myproject/DEVS.yml
+```
+
+📖 **[See ../../example-usage.md for detailed examples and scenarios](../../example-usage.md)**
+
+## Requirements
+
+- **Docker**: Container runtime
+- **VS Code**: With `code` command in PATH
+- **DevContainer CLI**: `npm install -g @devcontainers/cli`
+- **Project Requirements**: `.devcontainer/devcontainer.json` in target projects
+
+## Architecture
+
+### Container Naming
+Containers follow the pattern: `dev-<org>-<repo>-<dev-name>`
+
+Example: `dev-ideonate-devs-sally`, `dev-ideonate-devs-bob`
+
+### VS Code Window Management
+Each container gets unique workspace paths to ensure VS Code treats them as separate sessions.
+
+### Claude Authentication Sharing
+The tool creates symlinks so all containers for the same project share Claude authentication.
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/ideonate/devs.git
+cd devs/python-devs
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black devs tests
+
+# Type checking
+mypy devs
+```
+
+## License
+
+MIT License

devs_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+devs/__init__.py,sha256=ML7Y2NiarUaL6dwWM5MqdmUjyJN3Unq3VNm8ZogojZM,433
+devs/cli.py,sha256=IHn3aUXyaWVPFwL0iLlEseXtiPq7itkCijh4nJpTDC8,32727
+devs/config.py,sha256=EhCpt-DsRX6o2LU31rc5kBsgm_DQ1v7wywc9qptmyj4,1366
+devs/exceptions.py,sha256=7xO7ihJu_U6CupZPMv89B4N5EBSUcdj2OdA6GPAFPEE,490
+devs/core/__init__.py,sha256=TPy3eZi-AEztci_QZ37YAAl2zvUQlwBALpyiQx2ED7Q,363
+devs/core/integration.py,sha256=YOz03TvS5Rk8YYnPT_rbEB_EMjpkOY4Z7OEzeP-6ZZQ,11055
+devs/utils/__init__.py,sha256=f-sEWETPfW2Xkaxgd-l6FS-jIQAorLlQZOicIZvp-W0,638
+devs_cli-0.1.0.dist-info/licenses/LICENSE,sha256=bi2EUiv-lmC_quQVkNqzTYXJpjVarkPsVKfqhJl7ccQ,1067
+devs_cli-0.1.0.dist-info/METADATA,sha256=sqYKHWdUTuNXPRr0eEIJpl7p-7VkZSDcDO1gvTQTyN8,5278
+devs_cli-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+devs_cli-0.1.0.dist-info/entry_points.txt,sha256=s8-pgqZ1QvzPJgHP9vNxwBYdezmGsFdRUHacJPZ4WOs,39
+devs_cli-0.1.0.dist-info/top_level.txt,sha256=9RIVUPVGuOdO84qkBh_9XcKoTV7773o3py78wz2-IZk,5
+devs_cli-0.1.0.dist-info/RECORD,,

devs_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devs_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devs = devs.cli:main

devs_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dan Lester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devs_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devs