devs-cli 4.0.2__tar.gz → 4.0.4__tar.gz

{devs_cli-4.0.2/devs_cli.egg-info → devs_cli-4.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-cli
-Version: 4.0.2
+Version: 4.0.4
 Summary: DevContainer Management Tool - Manage multiple named devcontainers for any project
 Author: Dan Lester
 License-Expression: MIT

{devs_cli-4.0.2 → devs_cli-4.0.4}/devs/cli.py

@@ -3,6 +3,7 @@
 import os
 import sys
 import subprocess
+import traceback
 from functools import wraps
 from importlib.metadata import version, PackageNotFoundError
 
@@ -239,64 +240,112 @@ def start(dev_names: tuple, rebuild: bool, rebuild_if_changed: bool, live: bool,
 @click.option('--delay', default=2.0, help='Delay between opening VS Code windows (seconds)')
 @click.option('--live', is_flag=True, help='Start containers with current directory mounted as workspace')
 @click.option('--env', multiple=True, help='Environment variables to pass to container (format: VAR=value)')
+@click.option(
+    '--ssh',
+    'ssh_host',
+    default=None,
+    envvar='DEVS_SSH_HOST',
+    help=(
+        'Attach VS Code to a container ALREADY RUNNING on a remote SSH host '
+        '(e.g. Tailscale or any SSH-reachable Docker host). This is connection-only: '
+            'it does NOT provision anything. '
+        'It does NOT create, start, or sync the container — you must have already '
+            'started it on the remote host yourself (e.g. run `devs start` over there). '
+            'Only builds the VS Code Remote-SSH + attach URI. '
+        'Can also be set via the DEVS_SSH_HOST env var or ssh_host in DEVS.yml.'
+    ),
+)
 @debug_option
-def vscode(dev_names: tuple, delay: float, live: bool, env: tuple, debug: bool) -> None:
+def vscode(dev_names: tuple, delay: float, live: bool, env: tuple, ssh_host: str, debug: bool) -> None:
     """Open devcontainers in VS Code.
-    
+
     DEV_NAMES: One or more development environment names to open
-    
+
     Example: devs vscode sally bob
     Example: devs vscode sally --live  # Start with current directory mounted
     Example: devs vscode sally --env QUART_PORT=5001
+    Example: devs vscode sally --ssh myhost.tailnet.ts.net  # Attach to a container ALREADY running on myhost
     """
     check_dependencies()
     project = get_project()
-    
+
+    # If --ssh not given on CLI or env, check DEVS.yml
+    if not ssh_host:
+        ssh_host = DevsConfigLoader.load_ssh_host(project.info.name) or None
+
+    vscode_integration = VSCodeIntegration(project)
+
+    if ssh_host:
+        # SSH mode is attach-only: we do NOT provision anything. The container must
+        # already be running on the remote host (start it there yourself, e.g. by
+        # running `devs start` on the remote machine). We skip ContainerManager /
+        # WorkspaceManager entirely and only need the workspace path to construct the
+        # URI; derive it from the project name and dev name (no filesystem access needed).
+        workspace_dirs = []
+        valid_dev_names = []
+        for dev_name in dev_names:
+            workspace_name = project.get_workspace_name(dev_name)
+            # Use a synthetic Path so generate_devcontainer_uri can derive workspace_name.
+            # The path itself is never accessed locally in SSH mode.
+            workspace_dirs.append(config.workspaces_dir / workspace_name)
+            valid_dev_names.append(dev_name)
+
+        try:
+            success_count = vscode_integration.launch_multiple_devcontainers(
+                workspace_dirs,
+                valid_dev_names,
+                delay_between_windows=delay,
+                live=live,
+                ssh_host=ssh_host,
+            )
+            if success_count == 0:
+                console.print("❌ Failed to open any VS Code windows")
+        except VSCodeError as e:
+            console.print(f"❌ VS Code integration error: {e}")
+        return
+
+    # Local mode: manage containers and workspaces as normal
     container_manager = ContainerManager(project, config)
     workspace_manager = WorkspaceManager(project, config)
-    vscode = VSCodeIntegration(project)
-    
+
     workspace_dirs = []
     valid_dev_names = []
-    
+
     for dev_name in dev_names:
         console.print(f"   Preparing: {dev_name}")
-        
-        # Load environment variables from DEVS.yml and merge with CLI --env flags
+
         devs_env = DevsConfigLoader.load_env_vars(dev_name, project.info.name)
         cli_env = parse_env_vars(env) if env else {}
         extra_env = merge_env_vars(devs_env, cli_env) if devs_env or cli_env else None
-        
+
         if extra_env:
             console.print(f"🔧 Environment variables: {', '.join(f'{k}={v}' for k, v in extra_env.items())}")
-        
+
         try:
-            # Ensure workspace exists (handles live mode internally)
             workspace_dir = workspace_manager.create_workspace(dev_name, live=live)
-            
-            # Ensure container is running before launching VS Code (no auto-rebuild in CLI)
+
             if container_manager.ensure_container_running(dev_name, workspace_dir, check_rebuild=False, debug=debug, live=live, extra_env=extra_env):
                 workspace_dirs.append(workspace_dir)
                 valid_dev_names.append(dev_name)
             else:
                 console.print(f"   ❌ Failed to start container for {dev_name}, skipping...")
-                
+
         except (ContainerError, WorkspaceError) as e:
             console.print(f"   ❌ Error preparing {dev_name}: {e}")
             continue
-    
+
     if workspace_dirs:
         try:
-            success_count = vscode.launch_multiple_devcontainers(
-                workspace_dirs, 
+            success_count = vscode_integration.launch_multiple_devcontainers(
+                workspace_dirs,
                 valid_dev_names,
                 delay_between_windows=delay,
-                live=live
+                live=live,
             )
-            
+
             if success_count == 0:
                 console.print("❌ Failed to open any VS Code windows")
-                
+
         except VSCodeError as e:
             console.print(f"❌ VS Code integration error: {e}")
 
@@ -459,7 +508,6 @@ def claude(dev_name: str, prompt: str, auth: bool, reset_workspace: bool, live:
     except Exception as e:
         console.print(f"❌ Failed to configure Claude authentication: {e}")
         if debug:
-            import traceback
             console.print(traceback.format_exc())
         sys.exit(1)
 
@@ -632,7 +680,6 @@ def _handle_codex_auth(api_key: str, debug: bool) -> None:
     except Exception as e:
         console.print(f"❌ Failed to configure Codex authentication: {e}")
         if debug:
-            import traceback
             console.print(traceback.format_exc())
         sys.exit(1)
 

{devs_cli-4.0.2 → devs_cli-4.0.4}/devs/core/integration.py

@@ -1,9 +1,10 @@
 """VS Code and external tool integrations."""
 
+import json
 import subprocess
 import time
 from pathlib import Path
-from typing import List
+from typing import List, Optional
 
 from rich.console import Console
 
@@ -50,79 +51,94 @@ class VSCodeIntegration:
                 "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:
+    def generate_devcontainer_uri(
+        self,
+        workspace_dir: Path,
+        dev_name: str,
+        live: bool = False,
+        attach_to_existing: bool = True,
+        ssh_host: Optional[str] = None,
+    ) -> 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)
-            
+            ssh_host: If set, generate a Remote-SSH + attached-container URI for this host.
+                      The host can be a Tailscale MagicDNS name or any SSH-reachable hostname.
+
         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)
+
+            if ssh_host:
+                # JSON-encoded container info that includes the SSH host so VS Code's
+                # Dev Containers extension connects through Remote-SSH first.
+                # Container name is prefixed with "/" as Docker returns it in Names field.
+                container_info = {
+                    "containerName": f"/{container_name}",
+                    "settings": {"host": f"ssh://{ssh_host}"},
+                }
+                container_hex = json.dumps(container_info, separators=(",", ":")).encode("utf-8").hex()
+            else:
+                container_hex = container_name.encode("utf-8").hex()
+
             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_hex = workspace_dir.as_posix().encode("utf-8").hex()
+            # IMPORTANT: In live mode, use the actual host folder name because devcontainer CLI
+            # mounts the host directory directly and VS Code must match that path.
             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, 
+        self,
+        workspace_dir: Path,
         dev_name: str,
         new_window: bool = True,
-        live: bool = False
+        live: bool = False,
+        ssh_host: Optional[str] = None,
     ) -> bool:
         """Launch a devcontainer in VS Code.
-        
+
         Args:
             workspace_dir: Workspace directory path
-            dev_name: Development environment name 
+            dev_name: Development environment name
             new_window: Whether to open in a new window
             live: Whether to use live mode (mount current directory)
-            
+            ssh_host: If set, connect via Remote-SSH to this host then attach to the container.
+
         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']
-            
+            vscode_uri = self.generate_devcontainer_uri(
+                workspace_dir, dev_name, live, attach_to_existing=True, ssh_host=ssh_host
+            )
+
+            if ssh_host:
+                console.print(f"   🚀 Opening VS Code for: {dev_name} (via SSH: {ssh_host})")
+            else:
+                console.print(f"   🚀 Opening VS Code for: {dev_name}")
+
+            cmd = ["code"]
+
             if new_window:
-                cmd.append('--new-window')
-            
-            cmd.extend(['--folder-uri', vscode_uri])
-            
+                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(
@@ -131,74 +147,80 @@ class VSCodeIntegration:
                 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
+                debug=False,
+                live=live,
             )
-            
-            # Launch VS Code in background
+
             process = subprocess.Popen(
                 cmd,
                 env=env,
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
-                start_new_session=True
+                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], 
+        self,
+        workspace_dirs: List[Path],
         dev_names: List[str],
         delay_between_windows: float = 2.0,
-        live: bool = False
+        live: bool = False,
+        ssh_host: Optional[str] = None,
     ) -> 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)
-            
+            ssh_host: If set, connect via Remote-SSH to this host then attach to each container.
+
         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}")
-        
+
+        if ssh_host:
+            console.print(
+                f"📂 Opening {len(dev_names)} devcontainers in VS Code "
+                f"(via SSH: {ssh_host}) for project: {self.project.info.name}"
+            )
+        else:
+            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):
+                if self.launch_devcontainer(
+                    workspace_dir, dev_name, new_window=True, live=live, ssh_host=ssh_host
+                ):
                     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:

{devs_cli-4.0.2 → devs_cli-4.0.4/devs_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-cli
-Version: 4.0.2
+Version: 4.0.4
 Summary: DevContainer Management Tool - Manage multiple named devcontainers for any project
 Author: Dan Lester
 License-Expression: MIT

{devs_cli-4.0.2 → devs_cli-4.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devs-cli"
-version = "4.0.2"
+version = "4.0.4"
 description = "DevContainer Management Tool - Manage multiple named devcontainers for any project"
 readme = "README.md"
 requires-python = ">=3.8"

{devs_cli-4.0.2 → devs_cli-4.0.4}/tests/test_cli_vscode.py

@@ -1,4 +1,5 @@
 """Integration tests for the 'vscode' command."""
+import json
 from pathlib import Path
 from unittest.mock import MagicMock, Mock, patch
 
@@ -6,6 +7,8 @@ import pytest
 from click.testing import CliRunner
 
 from devs.cli import cli
+from devs.core.integration import VSCodeIntegration
+from devs.exceptions import VSCodeError, WorkspaceError
 
 
 class TestVSCodeCommand:
@@ -113,8 +116,6 @@ class TestVSCodeCommand:
                                         mock_container_manager_class, mock_get_project,
                                         cli_runner, temp_project):
         """Test vscode command when workspace creation fails."""
-        from devs.exceptions import WorkspaceError
-
         # Setup mocks
         mock_project = Mock()
         mock_project.info.name = "test-org-test-repo"
@@ -172,8 +173,6 @@ class TestVSCodeCommand:
                                 mock_container_manager_class, mock_get_project,
                                 cli_runner, temp_project):
         """Test vscode command when VS Code integration fails."""
-        from devs.exceptions import VSCodeError
-
         # Setup mocks
         mock_project = Mock()
         mock_project.info.name = "test-org-test-repo"
@@ -260,3 +259,151 @@ class TestVSCodeCommand:
 
         # Verify success
         assert result.exit_code == 0
+
+
+class TestVSCodeSSHMode:
+    """Tests for the SSH connection mode (--ssh / DEVS_SSH_HOST)."""
+
+    @patch('devs.cli.DevsConfigLoader.load_ssh_host', return_value=None)
+    @patch('devs.cli.get_project')
+    @patch('devs.cli.ContainerManager')
+    @patch('devs.cli.WorkspaceManager')
+    @patch('devs.cli.VSCodeIntegration')
+    def test_ssh_flag_skips_container_management(
+        self,
+        mock_vscode_class,
+        mock_workspace_manager_class,
+        mock_container_manager_class,
+        mock_get_project,
+        mock_load_ssh_host,
+        cli_runner,
+        temp_project,
+    ):
+        """When --ssh is given, ContainerManager and WorkspaceManager are not used."""
+        mock_project = Mock()
+        mock_project.info.name = "test-org-test-repo"
+        mock_project.get_workspace_name.return_value = "test-org-test-repo-alice"
+        mock_get_project.return_value = mock_project
+
+        mock_vscode = Mock()
+        mock_vscode.launch_multiple_devcontainers.return_value = 1
+        mock_vscode_class.return_value = mock_vscode
+
+        result = cli_runner.invoke(cli, ['vscode', 'alice', '--ssh', 'myhost.ts.net'])
+
+        assert result.exit_code == 0
+        mock_container_manager_class.assert_not_called()
+        mock_workspace_manager_class.assert_not_called()
+
+    @patch('devs.cli.DevsConfigLoader.load_ssh_host', return_value=None)
+    @patch('devs.cli.get_project')
+    @patch('devs.cli.ContainerManager')
+    @patch('devs.cli.WorkspaceManager')
+    @patch('devs.cli.VSCodeIntegration')
+    def test_ssh_flag_passes_host_to_launch(
+        self,
+        mock_vscode_class,
+        mock_workspace_manager_class,
+        mock_container_manager_class,
+        mock_get_project,
+        mock_load_ssh_host,
+        cli_runner,
+        temp_project,
+    ):
+        """--ssh host is forwarded to launch_multiple_devcontainers."""
+        mock_project = Mock()
+        mock_project.info.name = "test-org-test-repo"
+        mock_project.get_workspace_name.return_value = "test-org-test-repo-alice"
+        mock_get_project.return_value = mock_project
+
+        mock_vscode = Mock()
+        mock_vscode.launch_multiple_devcontainers.return_value = 1
+        mock_vscode_class.return_value = mock_vscode
+
+        cli_runner.invoke(cli, ['vscode', 'alice', '--ssh', 'dev.example.ts.net'])
+
+        call_kwargs = mock_vscode.launch_multiple_devcontainers.call_args
+        assert call_kwargs.kwargs.get('ssh_host') == 'dev.example.ts.net' or \
+               'dev.example.ts.net' in str(call_kwargs)
+
+    @patch('devs.cli.DevsConfigLoader.load_ssh_host', return_value='devs-yml-host.ts.net')
+    @patch('devs.cli.get_project')
+    @patch('devs.cli.ContainerManager')
+    @patch('devs.cli.WorkspaceManager')
+    @patch('devs.cli.VSCodeIntegration')
+    def test_ssh_host_from_devs_yml(
+        self,
+        mock_vscode_class,
+        mock_workspace_manager_class,
+        mock_container_manager_class,
+        mock_get_project,
+        mock_load_ssh_host,
+        cli_runner,
+        temp_project,
+    ):
+        """When ssh_host is in DEVS.yml and no --ssh flag, SSH mode is used."""
+        mock_project = Mock()
+        mock_project.info.name = "test-org-test-repo"
+        mock_project.get_workspace_name.return_value = "test-org-test-repo-alice"
+        mock_get_project.return_value = mock_project
+
+        mock_vscode = Mock()
+        mock_vscode.launch_multiple_devcontainers.return_value = 1
+        mock_vscode_class.return_value = mock_vscode
+
+        result = cli_runner.invoke(cli, ['vscode', 'alice'])
+
+        assert result.exit_code == 0
+        mock_container_manager_class.assert_not_called()
+        call_kwargs = mock_vscode.launch_multiple_devcontainers.call_args
+        assert call_kwargs.kwargs.get('ssh_host') == 'devs-yml-host.ts.net' or \
+               'devs-yml-host.ts.net' in str(call_kwargs)
+
+
+class TestSSHURIGeneration:
+    """Unit tests for generate_devcontainer_uri with SSH host."""
+
+    def _make_vsi(self):
+        mock_project = Mock()
+        mock_project.get_container_name.side_effect = lambda dn, prefix='dev': f'dev-test-org-repo-{dn}'
+        mock_project.get_workspace_name.side_effect = lambda dn: f'test-org-repo-{dn}'
+        with patch.object(VSCodeIntegration, '_check_vscode_cli', return_value=None):
+            vsi = VSCodeIntegration.__new__(VSCodeIntegration)
+            vsi.project = mock_project
+        return vsi
+
+    def test_local_uri_format_unchanged(self):
+        """Local URI format (no ssh_host) is unchanged from the existing behaviour."""
+        vsi = self._make_vsi()
+        workspace_dir = Path('/home/user/.devs/workspaces/test-org-repo-alice')
+        uri = vsi.generate_devcontainer_uri(workspace_dir, 'alice')
+        hex_part = uri.split('attached-container+')[1].split('/')[0]
+        decoded = bytes.fromhex(hex_part).decode('utf-8')
+        assert decoded == 'dev-test-org-repo-alice'
+        assert '/workspaces/test-org-repo-alice' in uri
+
+    def test_ssh_uri_contains_json_with_host(self):
+        """SSH URI encodes JSON with containerName (leading /) and settings.host."""
+        vsi = self._make_vsi()
+        workspace_dir = Path('/home/user/.devs/workspaces/test-org-repo-alice')
+        uri = vsi.generate_devcontainer_uri(workspace_dir, 'alice', ssh_host='myhost.ts.net')
+        hex_part = uri.split('attached-container+')[1].split('/')[0]
+        decoded = json.loads(bytes.fromhex(hex_part).decode('utf-8'))
+        assert decoded['containerName'] == '/dev-test-org-repo-alice'
+        assert decoded['settings']['host'] == 'ssh://myhost.ts.net'
+
+    def test_ssh_uri_workspace_path_correct(self):
+        """SSH URI workspace path matches the devs naming convention."""
+        vsi = self._make_vsi()
+        workspace_dir = Path('/home/user/.devs/workspaces/test-org-repo-alice')
+        uri = vsi.generate_devcontainer_uri(workspace_dir, 'alice', ssh_host='myhost.ts.net')
+        assert uri.endswith('/workspaces/test-org-repo-alice')
+
+    def test_ssh_host_with_port_is_preserved(self):
+        """SSH host including a port number is preserved verbatim."""
+        vsi = self._make_vsi()
+        workspace_dir = Path('/home/user/.devs/workspaces/test-org-repo-alice')
+        uri = vsi.generate_devcontainer_uri(workspace_dir, 'alice', ssh_host='myhost.ts.net:2222')
+        hex_part = uri.split('attached-container+')[1].split('/')[0]
+        decoded = json.loads(bytes.fromhex(hex_part).decode('utf-8'))
+        assert decoded['settings']['host'] == 'ssh://myhost.ts.net:2222'