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

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

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

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

@@ -246,12 +246,13 @@ def start(dev_names: tuple, rebuild: bool, rebuild_if_changed: bool, live: bool,
     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. '
+        'Open VS Code via direct Remote-SSH into a container ALREADY RUNNING and '
+        'reachable at this SSH host (e.g. its Tailscale name). The container is its '
+            'own ssh host, so this opens its /workspaces folder directly — no attach. '
+        'Connection-only: it does NOT create, start, or sync the container — start it '
+            'yourself first (e.g. `devs start` on the host). '
+        'Usually unnecessary: without --ssh, `devs vscode <dev>` auto-discovers the '
+            "container's tailnet name via the handshake start-tailscale.sh writes. "
         'Can also be set via the DEVS_SSH_HOST env var or ssh_host in DEVS.yml.'
     ),
 )
@@ -264,7 +265,8 @@ def vscode(dev_names: tuple, delay: float, live: bool, env: tuple, ssh_host: str
     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
+    Example: devs vscode sally  # Auto: direct Remote-SSH if sally's container is on the tailnet, else local
+    Example: devs vscode sally --ssh devs-myorg-myrepo-sally  # Force direct Remote-SSH into that node
     """
     check_dependencies()
     project = get_project()
@@ -275,79 +277,88 @@ def vscode(dev_names: tuple, delay: float, live: bool, env: tuple, ssh_host: str
 
     vscode_integration = VSCodeIntegration(project)
 
+    # Decide, per dev, whether to open via direct Remote-SSH (the container is its
+    # own tailnet ssh host) or to manage it locally. An explicit --ssh / env / DEVS.yml
+    # host forces SSH for every dev; otherwise auto-discover via the tailnet handshake
+    # that start-tailscale.sh writes (set only when the container is up + Tailscale SSH
+    # is on). Devs that don't resolve fall through to normal local mode.
     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 = []
+        ssh_hosts = {dev_name: ssh_host for dev_name in dev_names}
+    else:
+        ssh_hosts = {}
         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)
-
+            host = vscode_integration.resolve_tailnet_ssh_host(dev_name)
+            if host:
+                ssh_hosts[dev_name] = host
+
+    ssh_dev_names = [d for d in dev_names if d in ssh_hosts]
+    local_dev_names = [d for d in dev_names if d not in ssh_hosts]
+
+    # --- Direct Remote-SSH (attach-only: container already running on its host) ---
+    if ssh_dev_names:
+        for dev_name in ssh_dev_names:
+            console.print(f"   🔗 {dev_name} → ssh://{ssh_hosts[dev_name]} (direct Remote-SSH into container)")
+        # Synthetic workspace Paths: only the name is used to build the URI; the path
+        # is never accessed locally in SSH mode.
+        workspace_dirs = [config.workspaces_dir / project.get_workspace_name(d) for d in ssh_dev_names]
         try:
             success_count = vscode_integration.launch_multiple_devcontainers(
                 workspace_dirs,
-                valid_dev_names,
+                ssh_dev_names,
                 delay_between_windows=delay,
                 live=live,
-                ssh_host=ssh_host,
+                ssh_hosts=ssh_hosts,
             )
             if success_count == 0:
-                console.print("❌ Failed to open any VS Code windows")
+                console.print("❌ Failed to open any VS Code windows (Remote-SSH)")
         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)
+    # --- Local mode: manage containers and workspaces as normal ---
+    if local_dev_names:
+        container_manager = ContainerManager(project, config)
+        workspace_manager = WorkspaceManager(project, config)
 
-    workspace_dirs = []
-    valid_dev_names = []
+        workspace_dirs = []
+        valid_dev_names = []
 
-    for dev_name in dev_names:
-        console.print(f"   Preparing: {dev_name}")
+        for dev_name in local_dev_names:
+            console.print(f"   Preparing: {dev_name}")
 
-        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
+            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())}")
+            if extra_env:
+                console.print(f"🔧 Environment variables: {', '.join(f'{k}={v}' for k, v in extra_env.items())}")
 
-        try:
-            workspace_dir = workspace_manager.create_workspace(dev_name, live=live)
+            try:
+                workspace_dir = workspace_manager.create_workspace(dev_name, live=live)
 
-            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...")
+                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
+            except (ContainerError, WorkspaceError) as e:
+                console.print(f"   ❌ Error preparing {dev_name}: {e}")
+                continue
 
-    if workspace_dirs:
-        try:
-            success_count = vscode_integration.launch_multiple_devcontainers(
-                workspace_dirs,
-                valid_dev_names,
-                delay_between_windows=delay,
-                live=live,
-            )
+        if workspace_dirs:
+            try:
+                success_count = vscode_integration.launch_multiple_devcontainers(
+                    workspace_dirs,
+                    valid_dev_names,
+                    delay_between_windows=delay,
+                    live=live,
+                )
 
-            if success_count == 0:
-                console.print("❌ Failed to open any VS Code windows")
+                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}")
+            except VSCodeError as e:
+                console.print(f"❌ VS Code integration error: {e}")
 
 
 @cli.command()

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

@@ -1,6 +1,7 @@
 """VS Code and external tool integrations."""
 
 import json
+import shlex
 import subprocess
 import time
 from pathlib import Path
@@ -8,8 +9,9 @@ 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.config_hash import get_env_mount_path
 from devs_common.utils.devcontainer import prepare_devcontainer_environment
 
 console = Console()
@@ -25,13 +27,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(
@@ -40,17 +48,45 @@ 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 resolve_tailnet_ssh_host(self, dev_name: str) -> Optional[str]:
+        """Discover a container's own tailnet SSH name via the writeback handshake.
+
+        Joins docker <-> tailnet by docker container id, WITHOUT `docker exec`:
+        ``docker inspect`` the container for its hostname (== its short container id,
+        == the ``$HOSTNAME`` start-tailscale.sh keyed its handshake file by), then read
+        that file out of the host-shared env mount. Returns the short MagicDNS name
+        (e.g. ``devs-acme-app-eamonn-1``) only when the container is up AND Tailscale
+        SSH is on; otherwise None (caller falls back to local mode).
+        """
+        container_name = self.project.get_container_name(dev_name)
+        try:
+            inspect = subprocess.run(
+                ["docker", "inspect", "--format", "{{.Config.Hostname}}", container_name],
+                capture_output=True, text=True, check=False,
+            )
+        except FileNotFoundError:
+            return None  # no docker here
+        if inspect.returncode != 0:
+            return None  # container doesn't exist / not inspectable
+        container_id = inspect.stdout.strip()
+        if not container_id:
+            return None
+
+        handshake = get_env_mount_path(self.project.info.name) / "ts-nodes" / f"{container_id}.json"
+        if not handshake.exists():
+            return None
+        try:
+            data = json.loads(handshake.read_text())
+        except (OSError, ValueError):
+            return None
+        if not data.get("ssh"):
+            return None  # on the tailnet but not accepting SSH
+        return data.get("short") or None
+
     def generate_devcontainer_uri(
         self,
         workspace_dir: Path,
@@ -66,39 +102,81 @@ class VSCodeIntegration:
             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.
+            ssh_host: If set, generate a plain Remote-SSH folder URI for this host.
+                      In the devs+Tailscale model the container IS its own SSH host
+                      (you SSH straight into it — there's no separate Docker daemon to
+                      attach through), so this is NOT an attached-container URI.
 
         Returns:
             VS Code devcontainer URI
         """
+        # 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)
+
+        if ssh_host:
+            # Direct Remote-SSH INTO the container. With Tailscale the container is its
+            # own tailnet node running Tailscale SSH, so VS Code opens the in-container
+            # workspace folder over SSH — no Docker host, no attach. Wrapping this in an
+            # attached-container URI would make VS Code SSH in and then hunt for a Docker
+            # daemon that isn't there.
+            return f"vscode-remote://ssh-remote+{ssh_host}/workspaces/{workspace_name}"
+
         if attach_to_existing:
             container_name = self.project.get_container_name(dev_name)
-            workspace_name = workspace_dir.name if live else self.project.get_workspace_name(dev_name)
+            container_hex = container_name.encode("utf-8").hex()
+            return f"vscode-remote://attached-container+{container_hex}/workspaces/{workspace_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()
+        # Create new container from devcontainer.json
+        workspace_hex = workspace_dir.as_posix().encode("utf-8").hex()
+        return f"vscode-remote://dev-container+{workspace_hex}/workspaces/{workspace_name}"
+
+    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 for this container.
+
+        When an SSH host is set we print only the Remote-SSH command (the plain
+        attached-container command wouldn't work from another machine and is just
+        noise). Otherwise we print the local attached-container command.
+        """
+        if ssh_host:
+            ssh_cmd = self._format_code_command(workspace_dir, dev_name, live, new_window, ssh_host)
+            console.print(f"   📋 VS Code command (Remote-SSH: {ssh_host}):")
+            console.print(f"      {ssh_cmd}")
+            return
+
+        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}")
 
-            vscode_uri = f"vscode-remote://attached-container+{container_hex}/workspaces/{workspace_name}"
-        else:
-            # Original behavior: create new container from devcontainer.json
-            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)
-            vscode_uri = f"vscode-remote://dev-container+{workspace_hex}/workspaces/{workspace_name}"
-
-        return vscode_uri
-    
     def launch_devcontainer(
         self,
         workspace_dir: Path,
@@ -127,11 +205,6 @@ class VSCodeIntegration:
                 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:
@@ -139,6 +212,34 @@ class VSCodeIntegration:
 
             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 — just point to the command printed above and stop here.
+            if not self.code_available:
+                if ssh_host:
+                    # SSH mode is attach-only: we never created/started the container,
+                    # so we can't claim it's ready. The user must ensure it's running
+                    # on the remote host themselves.
+                    console.print(
+                        f"   ⚠️  VS Code 'code' command not found here — printed the attach "
+                        f"URI only. Make sure the container is already running on '{ssh_host}', "
+                        "then run the command above from a machine with VS Code installed."
+                    )
+                else:
+                    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(
@@ -177,6 +278,7 @@ class VSCodeIntegration:
         delay_between_windows: float = 2.0,
         live: bool = False,
         ssh_host: Optional[str] = None,
+        ssh_hosts: Optional[dict] = None,
     ) -> int:
         """Launch multiple devcontainers in separate VS Code windows.
 
@@ -185,7 +287,10 @@ class VSCodeIntegration:
             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.
+            ssh_host: If set, connect every dev via direct Remote-SSH to this host.
+            ssh_hosts: Optional per-dev override mapping ``dev_name -> ssh host``
+                (each container is its own tailnet host, so they differ). Falls back
+                to ``ssh_host`` for any dev not present in the map.
 
         Returns:
             Number of successfully launched windows
@@ -193,10 +298,11 @@ class VSCodeIntegration:
         if len(workspace_dirs) != len(dev_names):
             raise VSCodeError("Workspace directories and dev names lists must have same length")
 
-        if ssh_host:
+        ssh_hosts = ssh_hosts or {}
+        if ssh_host or ssh_hosts:
             console.print(
                 f"📂 Opening {len(dev_names)} devcontainers in VS Code "
-                f"(via SSH: {ssh_host}) for project: {self.project.info.name}"
+                f"(via Remote-SSH) for project: {self.project.info.name}"
             )
         else:
             console.print(f"📂 Opening {len(dev_names)} devcontainers in VS Code for project: {self.project.info.name}")
@@ -204,9 +310,10 @@ class VSCodeIntegration:
         success_count = 0
 
         for workspace_dir, dev_name in zip(workspace_dirs, dev_names):
+            host = ssh_hosts.get(dev_name, ssh_host)
             try:
                 if self.launch_devcontainer(
-                    workspace_dir, dev_name, new_window=True, live=live, ssh_host=ssh_host
+                    workspace_dir, dev_name, new_window=True, live=live, ssh_host=host
                 ):
                     success_count += 1
 
@@ -217,7 +324,7 @@ class VSCodeIntegration:
                 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}'")
 

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

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

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

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

{devs_cli-4.0.4 → devs_cli-5.0.0}/tests/test_integration.py

@@ -20,12 +20,32 @@ class TestVSCodeIntegration:
             assert integration.project == mock_project
 
     def test_init_vscode_not_found(self, mock_project):
-        """Test VSCodeIntegration when VS Code not found."""
+        """VSCodeIntegration is non-fatal when the 'code' command is missing.
+
+        On a headless remote dev box there may be no local 'code' command; we still
+        want to construct the integration (and later print the command) rather than
+        abort.
+        """
+        with patch('subprocess.run') as mock_run:
+            mock_run.side_effect = FileNotFoundError()
+            integration = VSCodeIntegration(mock_project)
+            assert integration.code_available is False
+
+    def test_launch_devcontainer_prints_command_when_code_missing(self, mock_project):
+        """When 'code' is unavailable, launch prints the command and reports success."""
         with patch('subprocess.run') as mock_run:
             mock_run.side_effect = FileNotFoundError()
-            with pytest.raises(DependencyError) as exc_info:
-                VSCodeIntegration(mock_project)
-            assert "code" in str(exc_info.value)
+            integration = VSCodeIntegration(mock_project)
+
+        with patch('subprocess.Popen') as mock_popen:
+            result = integration.launch_devcontainer(Path("/tmp/workspace"), "alice")
+
+        # Treated as handled, and no 'code' process was launched.
+        assert result is True
+        assert not any(
+            c.args and c.args[0] and c.args[0][0] == "code"
+            for c in mock_popen.call_args_list
+        )
 
     def test_generate_devcontainer_uri_attach(self, mock_project):
         """Test devcontainer URI generation for attaching to existing container."""