devs-cli 4.0.3__py3-none-any.whl → 4.0.7__py3-none-any.whl

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/core/integration.py

@@ -1,13 +1,15 @@
 """VS Code and external tool integrations."""
 
+import json
+import shlex
 import subprocess
 import time
 from pathlib import Path
-from typing import List
+from typing import List, Optional
 
 from rich.console import Console
 
-from ..exceptions import VSCodeError, DependencyError
+from ..exceptions import VSCodeError
 from devs_common.core.project import Project
 from devs_common.utils.devcontainer import prepare_devcontainer_environment
 
@@ -24,13 +26,19 @@ class VSCodeIntegration:
             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
+        self.code_available = self._check_vscode_cli()
+
+    def _check_vscode_cli(self) -> bool:
+        """Check if the VS Code 'code' CLI is available.
+
+        This is intentionally non-fatal: on a remote/headless dev box (e.g. one you
+        only ever reach over SSH) there may be no local 'code' command, but it is still
+        useful to start the container and print the URI / command you'd run from a
+        machine that does have VS Code. Callers consult ``self.code_available`` and fall
+        back to printing the command instead of launching.
+
+        Returns:
+            True if the 'code' command is available, False otherwise.
         """
         try:
             result = subprocess.run(
@@ -39,90 +47,156 @@ class VSCodeIntegration:
                 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."
-                )
+            return result.returncode == 0
         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."
-            )
+            return False
     
-    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 _format_code_command(
+        self,
+        workspace_dir: Path,
+        dev_name: str,
+        live: bool,
+        new_window: bool,
+        ssh_host: Optional[str],
+    ) -> str:
+        """Build the 'code' command string for opening a container.
+
+        Returned as a copy/paste-ready, shell-quoted string so it can be printed and
+        run from another machine that has VS Code installed.
+        """
+        vscode_uri = self.generate_devcontainer_uri(
+            workspace_dir, dev_name, live, attach_to_existing=True, ssh_host=ssh_host
+        )
+        cmd = ["code"]
+        if new_window:
+            cmd.append("--new-window")
+        cmd.extend(["--folder-uri", vscode_uri])
+        return " ".join(shlex.quote(part) for part in cmd)
+
+    def _print_code_commands(
+        self,
+        workspace_dir: Path,
+        dev_name: str,
+        live: bool,
+        new_window: bool,
+        ssh_host: Optional[str],
+    ) -> None:
+        """Print the 'code' command(s) for this container.
+
+        Always prints the plain (non-SSH) command. When an SSH host is set, the SSH
+        form is printed too, so you can copy whichever matches where you're running it.
+        """
+        if ssh_host:
+            ssh_cmd = self._format_code_command(workspace_dir, dev_name, live, new_window, ssh_host)
+            console.print(f"   📋 VS Code command (via SSH: {ssh_host}):")
+            console.print(f"      {ssh_cmd}")
+
+        plain_cmd = self._format_code_command(workspace_dir, dev_name, live, new_window, None)
+        console.print(f"   📋 VS Code command:")
+        console.print(f"      {plain_cmd}")
+
     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
+            )
+
+            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])
+
+            # Always print the command(s) so they can be copied and run elsewhere.
+            self._print_code_commands(workspace_dir, dev_name, live, new_window, ssh_host)
+
+            # No local 'code' command (e.g. a headless remote dev box reached over SSH):
+            # don't fail — the container is already prepared, so just point to the
+            # command printed above and stop here.
+            if not self.code_available:
+                console.print(
+                    f"   ⚠️  VS Code 'code' command not found here — container is ready, "
+                    "but VS Code can't be launched from this machine. "
+                    "Run the command above from a machine with VS Code installed."
+                )
+                return True
+
+            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}")
+
             # Set environment variables using shared function
             container_workspace_name = self.project.get_workspace_name(dev_name)
             env = prepare_devcontainer_environment(
@@ -131,74 +205,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:
+
+        if success_count > 0 and self.code_available:
             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.3.dist-info → devs_cli-4.0.7.dist-info}/METADATA

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

devs_cli-4.0.7.dist-info/RECORD

@@ -0,0 +1,13 @@
+devs/__init__.py,sha256=dMk0J_JrmBmknPvt6HNUa04qxgHYpxhnIXa3PZFk_N0,571
+devs/cli.py,sha256=wRqKwdyGYAqemrabrH7NhMpBYX4iFJpowWxwDqptYmk,44125
+devs/config.py,sha256=DaS2_1x0h63cHn34RmWbEhUx_1u3-sAo16tM3AXMKfQ,1561
+devs/exceptions.py,sha256=7xO7ihJu_U6CupZPMv89B4N5EBSUcdj2OdA6GPAFPEE,490
+devs/core/__init__.py,sha256=TPy3eZi-AEztci_QZ37YAAl2zvUQlwBALpyiQx2ED7Q,363
+devs/core/integration.py,sha256=cM3bIok06Z4faIkTyF8h35FeKdHpnx3_h2mXnJ1SaW0,13935
+devs/utils/__init__.py,sha256=f-sEWETPfW2Xkaxgd-l6FS-jIQAorLlQZOicIZvp-W0,638
+devs_cli-4.0.7.dist-info/licenses/LICENSE,sha256=bi2EUiv-lmC_quQVkNqzTYXJpjVarkPsVKfqhJl7ccQ,1067
+devs_cli-4.0.7.dist-info/METADATA,sha256=kak8KcJlQeXQGLObaeobYBGZWS9CsCFOOaRYMu9j6B0,5282
+devs_cli-4.0.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devs_cli-4.0.7.dist-info/entry_points.txt,sha256=s8-pgqZ1QvzPJgHP9vNxwBYdezmGsFdRUHacJPZ4WOs,39
+devs_cli-4.0.7.dist-info/top_level.txt,sha256=9RIVUPVGuOdO84qkBh_9XcKoTV7773o3py78wz2-IZk,5
+devs_cli-4.0.7.dist-info/RECORD,,

devs_cli-4.0.3.dist-info/RECORD

@@ -1,13 +0,0 @@
-devs/__init__.py,sha256=dMk0J_JrmBmknPvt6HNUa04qxgHYpxhnIXa3PZFk_N0,571
-devs/cli.py,sha256=tlmKeM-sk3SRRXhRegbL35hm0PR3NFq-N-UgPzNE3gA,42127
-devs/config.py,sha256=DaS2_1x0h63cHn34RmWbEhUx_1u3-sAo16tM3AXMKfQ,1561
-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-4.0.3.dist-info/licenses/LICENSE,sha256=bi2EUiv-lmC_quQVkNqzTYXJpjVarkPsVKfqhJl7ccQ,1067
-devs_cli-4.0.3.dist-info/METADATA,sha256=-Pi2rvXvVojes91djeFRVFExTqE4gvqHYls5yUeN168,5282
-devs_cli-4.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-devs_cli-4.0.3.dist-info/entry_points.txt,sha256=s8-pgqZ1QvzPJgHP9vNxwBYdezmGsFdRUHacJPZ4WOs,39
-devs_cli-4.0.3.dist-info/top_level.txt,sha256=9RIVUPVGuOdO84qkBh_9XcKoTV7773o3py78wz2-IZk,5
-devs_cli-4.0.3.dist-info/RECORD,,