devs-cli 2.0.5__tar.gz → 2.0.7__tar.gz

{devs_cli-2.0.5/devs_cli.egg-info → devs_cli-2.0.7}/PKG-INFO

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

{devs_cli-2.0.5 → devs_cli-2.0.7}/devs/cli.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from .core import Project, ContainerManager, WorkspaceManager
 from .core.integration import VSCodeIntegration, ExternalToolIntegration
 from devs_common.devs_config import DevsConfigLoader
+from devs_common.utils.repo_cache import RepoCache
 from .exceptions import (
     DevsError,
     ProjectNotFoundError,
@@ -87,7 +88,12 @@ def debug_option(f):
 
 def check_dependencies() -> None:
     """Check and report on dependencies."""
-    integration = ExternalToolIntegration(Project())
+    try:
+        project = Project()
+    except Exception:
+        # Outside a git repo (e.g. using --repo), use a dummy project
+        project = None
+    integration = ExternalToolIntegration(project)
     missing = integration.get_missing_dependencies()
     
     if missing:
@@ -104,13 +110,29 @@ def check_dependencies() -> None:
 
 
 def get_project() -> Project:
-    """Get project instance with error handling."""
+    """Get project instance with error handling.
+
+    If the CLI was invoked with --repo, the repo is cloned/updated
+    into the local cache and the Project is created from that path.
+    Otherwise, the current working directory is used.
+    """
+    # Check for --repo from the CLI group context
+    repo = None
     try:
-        project = Project()
-        # No longer require devcontainer config upfront - 
-        # WorkspaceManager will provide default template if needed
+        ctx = click.get_current_context()
+        repo = ctx.obj.get('REPO') if ctx.obj else None
+    except RuntimeError:
+        pass
+
+    try:
+        if repo:
+            repo_cache = RepoCache(cache_dir=config.repo_cache_dir)
+            repo_path = repo_cache.ensure_repo(repo)
+            project = Project(project_dir=repo_path)
+        else:
+            project = Project()
         return project
-    except ProjectNotFoundError as e:
+    except (ProjectNotFoundError, DevsError) as e:
         console.print(f"❌ {e}")
         sys.exit(1)
 
@@ -132,14 +154,16 @@ def _get_version(ctx: click.Context, param: click.Parameter, value: bool) -> Non
 @click.group()
 @click.option('--version', is_flag=True, callback=_get_version, expose_value=False, is_eager=True, help='Show version and exit.')
 @click.option('--debug', is_flag=True, help='Show debug tracebacks on error')
+@click.option('--repo', default=None, help='GitHub org/repo (e.g. "ideonate/devs") to clone into cache instead of using CWD')
 @click.pass_context
-def cli(ctx, debug: bool) -> None:
+def cli(ctx, debug: bool, repo: str) -> None:
     """DevContainer Management Tool
 
     Manage multiple named devcontainers for any project.
     """
     ctx.ensure_object(dict)
     ctx.obj['DEBUG'] = debug
+    ctx.obj['REPO'] = repo
 
 
 @cli.command()
@@ -794,7 +818,7 @@ def runtests(dev_name: str, reset_workspace: bool, live: bool, env: tuple, debug
 
 
 @cli.command()
-@click.argument('dev_name', required=False)
+@click.argument('dev_name')
 @click.option('--auth', is_flag=True, help='Set up tunnel authentication (interactive, one-time setup)')
 @click.option('--status', is_flag=True, help='Check tunnel status instead of starting')
 @click.option('--kill', 'kill_tunnel', is_flag=True, help='Kill running tunnel')
@@ -809,26 +833,18 @@ def tunnel(dev_name: str, auth: bool, status: bool, kill_tunnel: bool, live: boo
     tunnel service, and your local VS Code connects through that.
 
     First-time setup requires authentication:
-      devs tunnel --auth
+      devs tunnel <name> --auth
 
-    After that, tunnels run in the background automatically.
+    Auth is stored in a bind-mounted directory so it persists across
+    all containers on this machine.
 
     DEV_NAME: Development environment name
 
-    Example: devs tunnel --auth          # One-time auth setup (no project needed)
+    Example: devs tunnel sally --auth    # One-time auth setup
     Example: devs tunnel sally           # Start tunnel (background)
     Example: devs tunnel sally --status  # Check tunnel status
     Example: devs tunnel sally --kill    # Stop running tunnel
     """
-    # Handle authentication mode - no project or dev_name needed
-    if auth:
-        _handle_tunnel_auth(debug=debug)
-        return
-
-    # All other modes require dev_name
-    if not dev_name:
-        raise click.UsageError("DEV_NAME is required unless using --auth")
-
     check_dependencies()
     project = get_project()
 
@@ -847,7 +863,17 @@ def tunnel(dev_name: str, auth: bool, status: bool, kill_tunnel: bool, live: boo
         # Ensure workspace exists (handles live mode internally)
         workspace_dir = workspace_manager.create_workspace(dev_name, live=live)
 
-        if status:
+        if auth:
+            # Interactive authentication inside the container
+            container_manager.tunnel_auth(
+                dev_name=dev_name,
+                workspace_dir=workspace_dir,
+                debug=debug,
+                live=live,
+                extra_env=extra_env
+            )
+
+        elif status:
             # Check tunnel status
             is_running, status_msg = container_manager.get_tunnel_status(
                 dev_name=dev_name,
@@ -889,63 +915,6 @@ def tunnel(dev_name: str, auth: bool, status: bool, kill_tunnel: bool, live: boo
         sys.exit(1)
 
 
-def _handle_tunnel_auth(debug: bool) -> None:
-    """Handle VS Code tunnel authentication.
-
-    Runs the VS Code CLI on the host to authenticate. Auth is stored
-    in ~/.devs/vscode-cli/ and bind-mounted into containers.
-    """
-    try:
-        config.ensure_directories()
-
-        console.print("🔐 Setting up VS Code tunnel authentication...")
-        console.print(f"   Configuration will be saved to: {config.vscode_cli_dir}")
-        console.print("")
-        console.print("   Starting interactive authentication...")
-        console.print("   Follow the prompts to authenticate with GitHub")
-        console.print("")
-
-        env = os.environ.copy()
-        env['VSCODE_CLI_DATA_DIR'] = str(config.vscode_cli_dir)
-
-        cmd = ['code', 'tunnel', 'user', 'login', '--provider', 'github']
-
-        if debug:
-            console.print(f"[dim]Running: {' '.join(cmd)}[/dim]")
-            console.print(f"[dim]VSCODE_CLI_DATA_DIR: {config.vscode_cli_dir}[/dim]")
-
-        result = subprocess.run(cmd, env=env, check=False)
-
-        if result.returncode == 0:
-            console.print("")
-            console.print("✅ Tunnel authentication configured successfully!")
-            console.print(f"   Configuration saved to: {config.vscode_cli_dir}")
-            console.print("   This authentication will be shared across all devcontainers")
-            console.print("")
-            console.print("💡 You can now start tunnels from any project:")
-            console.print("   devs tunnel <name>")
-        else:
-            console.print("")
-            console.print("[yellow]Authentication was cancelled or failed.[/yellow]")
-
-    except FileNotFoundError:
-        console.print("❌ VS Code CLI not found on host machine")
-        console.print("")
-        console.print("Please install VS Code CLI first:")
-        console.print("   https://code.visualstudio.com/docs/editor/command-line")
-        console.print("")
-        console.print("Or install the standalone CLI:")
-        console.print("   curl -fSL 'https://update.code.visualstudio.com/latest/cli-linux-x64/stable' -o /tmp/vscode-cli.tar.gz")
-        console.print("   sudo tar -xf /tmp/vscode-cli.tar.gz -C /usr/local/bin")
-        sys.exit(1)
-
-    except Exception as e:
-        console.print(f"❌ Failed to configure tunnel authentication: {e}")
-        if debug:
-            import traceback
-            console.print(traceback.format_exc())
-        sys.exit(1)
-
 
 @cli.command()
 @click.option('--all-projects', is_flag=True, help='List containers for all projects')
@@ -955,25 +924,56 @@ def list(all_projects: bool) -> None:
     
     if all_projects:
         console.print("📋 All devcontainers:")
-        # This would require a more complex implementation
-        console.print("   --all-projects not implemented yet")
+        console.print("")
+
+        try:
+            containers = ContainerManager.list_all_containers()
+
+            if not containers:
+                console.print("   No active devcontainers found")
+                return
+
+            table = Table()
+            table.add_column("Project", style="magenta")
+            table.add_column("Name", style="cyan")
+            table.add_column("Mode", style="yellow")
+            table.add_column("Status", style="green")
+            table.add_column("Container", style="dim")
+            table.add_column("Created", style="dim")
+
+            for container in containers:
+                created_str = container.created.strftime("%Y-%m-%d %H:%M") if container.created else "unknown"
+                mode = "live" if container.labels.get('devs.live') == 'true' else "copy"
+                table.add_row(
+                    container.project_name,
+                    container.dev_name,
+                    mode,
+                    container.status,
+                    container.name,
+                    created_str
+                )
+
+            console.print(table)
+
+        except ContainerError as e:
+            console.print(f"❌ Error listing containers: {e}")
         return
-    
+
     project = get_project()
     container_manager = ContainerManager(project, config)
-    
+
     console.print(f"📋 Active devcontainers for project: {project.info.name}")
     console.print("")
-    
+
     try:
         containers = container_manager.list_containers()
-        
+
         if not containers:
             console.print("   No active devcontainers found")
             console.print("")
             console.print("💡 Start some with: devs start <dev-name>")
             return
-        
+
         # Create a table
         table = Table()
         table.add_column("Name", style="cyan")
@@ -981,7 +981,7 @@ def list(all_projects: bool) -> None:
         table.add_column("Status", style="green")
         table.add_column("Container", style="dim")
         table.add_column("Created", style="dim")
-        
+
         for container in containers:
             created_str = container.created.strftime("%Y-%m-%d %H:%M") if container.created else "unknown"
             mode = "live" if container.labels.get('devs.live') == 'true' else "copy"
@@ -992,13 +992,13 @@ def list(all_projects: bool) -> None:
                 container.name,
                 created_str
             )
-        
+
         console.print(table)
         console.print("")
         console.print("💡 Open with: devs vscode <dev-name>")
         console.print("💡 Shell into: devs shell <dev-name>")
         console.print("💡 Stop with: devs stop <dev-name>")
-        
+
     except ContainerError as e:
         console.print(f"❌ Error listing containers: {e}")
 
@@ -1007,7 +1007,7 @@ def list(all_projects: bool) -> None:
 def status() -> None:
     """Show project and dependency status."""
     try:
-        project = Project()
+        project = get_project()
         
         console.print(f"📁 Project: {project.info.name}")
         console.print(f"   Directory: {project.info.directory}")

{devs_cli-2.0.5 → devs_cli-2.0.7}/devs/config.py

@@ -17,6 +17,7 @@ class Config(BaseConfig):
     CLAUDE_CONFIG_DIR = Path.home() / ".devs" / "claudeconfig"
     CODEX_CONFIG_DIR = Path.home() / ".devs" / "codexconfig"
     VSCODE_CLI_DIR = Path.home() / ".devs" / "vscode-cli"
+    REPO_CACHE_DIR = Path.home() / ".devs" / "repocache"
 
     @property
     def container_labels(self) -> Dict[str, str]:
@@ -47,6 +48,12 @@ class Config(BaseConfig):
             self.vscode_cli_dir = Path(vscode_cli_env)
         else:
             self.vscode_cli_dir = self.VSCODE_CLI_DIR
+
+        repo_cache_env = os.getenv("DEVS_REPO_CACHE_DIR")
+        if repo_cache_env:
+            self.repo_cache_dir = Path(repo_cache_env)
+        else:
+            self.repo_cache_dir = self.REPO_CACHE_DIR
     
     def get_default_workspaces_dir(self) -> Path:
         """Get default workspaces directory for CLI package."""

{devs_cli-2.0.5 → devs_cli-2.0.7/devs_cli.egg-info}/PKG-INFO

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

{devs_cli-2.0.5 → devs_cli-2.0.7}/devs_cli.egg-info/SOURCES.txt

@@ -26,4 +26,5 @@ tests/test_error_parsing.py
 tests/test_integration.py
 tests/test_live_mode.py
 tests/test_project.py
+tests/test_repo_cache.py
 tests/test_workspace_manager.py

{devs_cli-2.0.5 → devs_cli-2.0.7}/pyproject.toml

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

{devs_cli-2.0.5 → devs_cli-2.0.7}/tests/test_cli_misc.py

@@ -69,21 +69,50 @@ class TestListCommand:
             assert result.exit_code == 0
             assert "No active devcontainers found" in result.output
     
-    @patch('devs.cli.Project')
-    def test_list_all_containers(self, mock_project_class, cli_runner, temp_project):
-        """Test listing all devs containers - --all-projects not yet implemented."""
-        # Setup mocks
-        mock_project = Mock()
-        mock_project.path = temp_project
-        mock_project.info.name = "test-org-test-repo"
-        mock_project_class.return_value = mock_project
+    @patch('devs.cli.ContainerManager')
+    def test_list_all_projects(self, mock_container_manager_class, cli_runner, temp_project):
+        """Test listing containers across all projects."""
+        mock_container_manager_class.list_all_containers.return_value = [
+            MockContainer("/dev-org-a-repo-a-alice", "running", {
+                "devs.project": "org-a-repo-a",
+                "devs.name": "alice",
+                "devs.managed": "true"
+            }),
+            MockContainer("/dev-org-a-repo-a-bob", "exited", {
+                "devs.project": "org-a-repo-a",
+                "devs.name": "bob",
+                "devs.managed": "true"
+            }),
+            MockContainer("/dev-org-b-repo-b-charlie", "running", {
+                "devs.project": "org-b-repo-b",
+                "devs.name": "charlie",
+                "devs.managed": "true"
+            }),
+        ]
+
+        result = cli_runner.invoke(cli, ['list', '--all-projects'])
+
+        assert result.exit_code == 0
+        assert "All devcontainers" in result.output
+        assert "org-a-repo-a" in result.output
+        assert "org-b-repo-b" in result.output
+        assert "alice" in result.output
+        assert "bob" in result.output
+        assert "charlie" in result.output
+        assert "running" in result.output
+        assert "exited" in result.output
+        # Should include Project column
+        mock_container_manager_class.list_all_containers.assert_called_once()
+
+    @patch('devs.cli.ContainerManager')
+    def test_list_all_projects_no_containers(self, mock_container_manager_class, cli_runner, temp_project):
+        """Test --all-projects when no containers exist."""
+        mock_container_manager_class.list_all_containers.return_value = []
 
-        # Run command with --all-projects (not --all)
         result = cli_runner.invoke(cli, ['list', '--all-projects'])
 
-        # --all-projects is not implemented yet, verify the output message
         assert result.exit_code == 0
-        assert "--all-projects not implemented yet" in result.output
+        assert "No active devcontainers found" in result.output
 
 
 class TestStatusCommand:

{devs_cli-2.0.5 → devs_cli-2.0.7}/tests/test_container_manager.py

@@ -125,6 +125,77 @@ class TestContainerManager:
                 assert all(isinstance(c, ContainerInfo) for c in containers)
                 assert {c.dev_name for c in containers} == {"alice", "bob"}
 
+    def test_list_all_containers(self):
+        """Test listing all devs-managed containers across all projects."""
+        with patch('devs_common.core.container.DockerClient') as mock_docker_client_class:
+            mock_docker_instance = MagicMock()
+            mock_docker_client_class.return_value = mock_docker_instance
+
+            mock_docker_instance.find_containers_by_labels.return_value = [
+                {
+                    'name': 'dev-org-a-repo-a-alice',
+                    'id': 'abc123',
+                    'status': 'running',
+                    'labels': {
+                        'devs.managed': 'true',
+                        'devs.project': 'org-a-repo-a',
+                        'devs.dev': 'alice'
+                    },
+                    'created': '2025-01-01T00:00:00.000000Z'
+                },
+                {
+                    'name': 'dev-org-b-repo-b-bob',
+                    'id': 'def456',
+                    'status': 'exited',
+                    'labels': {
+                        'devs.managed': 'true',
+                        'devs.project': 'org-b-repo-b',
+                        'devs.dev': 'bob'
+                    },
+                    'created': '2025-01-02T00:00:00.000000Z'
+                },
+                {
+                    'name': 'dev-org-a-repo-a-charlie',
+                    'id': 'ghi789',
+                    'status': 'running',
+                    'labels': {
+                        'devs.managed': 'true',
+                        'devs.project': 'org-a-repo-a',
+                        'devs.dev': 'charlie'
+                    },
+                    'created': '2025-01-03T00:00:00.000000Z'
+                },
+            ]
+
+            containers = ContainerManager.list_all_containers()
+
+            # Verify it searched with devs.managed label
+            mock_docker_instance.find_containers_by_labels.assert_called_once_with(
+                {"devs.managed": "true"}
+            )
+
+            assert len(containers) == 3
+            assert all(isinstance(c, ContainerInfo) for c in containers)
+
+            # Verify sorted by project name then dev name
+            assert containers[0].project_name == "org-a-repo-a"
+            assert containers[0].dev_name == "alice"
+            assert containers[1].project_name == "org-a-repo-a"
+            assert containers[1].dev_name == "charlie"
+            assert containers[2].project_name == "org-b-repo-b"
+            assert containers[2].dev_name == "bob"
+
+    def test_list_all_containers_empty(self):
+        """Test listing all containers when none exist."""
+        with patch('devs_common.core.container.DockerClient') as mock_docker_client_class:
+            mock_docker_instance = MagicMock()
+            mock_docker_client_class.return_value = mock_docker_instance
+            mock_docker_instance.find_containers_by_labels.return_value = []
+
+            containers = ContainerManager.list_all_containers()
+
+            assert len(containers) == 0
+
     def test_stop_container_success(self, mock_project):
         """Test successful container stop."""
         with patch('devs_common.utils.docker_client.docker') as mock_docker:

devs_cli-2.0.7/tests/test_repo_cache.py

@@ -0,0 +1,198 @@
+"""Tests for RepoCache utility and --repo CLI option."""
+
+import subprocess
+from pathlib import Path
+from unittest.mock import MagicMock, Mock, patch, call
+
+import pytest
+from click.testing import CliRunner
+
+from devs_common.utils.repo_cache import RepoCache
+
+
+class TestRepoCache:
+    """Unit tests for the RepoCache class."""
+
+    def test_repo_name_to_dir_name(self):
+        cache = RepoCache(cache_dir=Path("/tmp/cache"))
+        assert cache._repo_name_to_dir_name("ideonate/devs") == "ideonate-devs"
+        assert cache._repo_name_to_dir_name("Org/Repo") == "org-repo"
+
+    def test_build_clone_url_no_token(self, monkeypatch):
+        monkeypatch.delenv("GH_TOKEN", raising=False)
+        monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+        cache = RepoCache()
+        assert cache._build_clone_url("org/repo") == "https://github.com/org/repo.git"
+
+    def test_build_clone_url_with_gh_token(self, monkeypatch):
+        monkeypatch.setenv("GH_TOKEN", "tok123")
+        monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+        cache = RepoCache()
+        assert cache._build_clone_url("org/repo") == "https://x-access-token:tok123@github.com/org/repo.git"
+
+    def test_build_clone_url_with_github_token(self, monkeypatch):
+        monkeypatch.delenv("GH_TOKEN", raising=False)
+        monkeypatch.setenv("GITHUB_TOKEN", "tok456")
+        cache = RepoCache()
+        assert cache._build_clone_url("org/repo") == "https://x-access-token:tok456@github.com/org/repo.git"
+
+    def test_build_clone_url_with_explicit_token(self, monkeypatch):
+        monkeypatch.delenv("GH_TOKEN", raising=False)
+        monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+        cache = RepoCache(token="mytoken")
+        assert cache._build_clone_url("org/repo") == "https://x-access-token:mytoken@github.com/org/repo.git"
+
+    def test_explicit_token_takes_priority(self, monkeypatch):
+        monkeypatch.setenv("GH_TOKEN", "envtoken")
+        cache = RepoCache(token="explicit")
+        assert cache._build_clone_url("org/repo") == "https://x-access-token:explicit@github.com/org/repo.git"
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_ensure_repo_clones_when_missing(self, mock_run, tmp_path):
+        cache = RepoCache(cache_dir=tmp_path)
+        mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+
+        path = cache.ensure_repo("ideonate/devs")
+
+        assert path == tmp_path / "ideonate-devs"
+        # First call should be git clone
+        clone_call = mock_run.call_args_list[0]
+        assert clone_call[0][0][0:2] == ["git", "clone"]
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_ensure_repo_updates_when_exists(self, mock_run, tmp_path):
+        # Pre-create repo directory with .git
+        repo_dir = tmp_path / "ideonate-devs"
+        repo_dir.mkdir()
+        (repo_dir / ".git").mkdir()
+
+        mock_run.return_value = Mock(returncode=0, stdout="refs/remotes/origin/main", stderr="")
+        cache = RepoCache(cache_dir=tmp_path)
+        path = cache.ensure_repo("ideonate/devs")
+
+        assert path == repo_dir
+        # Should call set-url then fetch, not clone
+        cmds = [c[0][0][:2] for c in mock_run.call_args_list]
+        assert ["git", "remote"] in cmds
+        assert ["git", "fetch"] in cmds
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_ensure_repo_with_branch(self, mock_run, tmp_path):
+        cache = RepoCache(cache_dir=tmp_path)
+        mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+
+        cache.ensure_repo("org/repo", branch="develop")
+
+        # Should have a checkout call with "develop"
+        checkout_calls = [
+            c for c in mock_run.call_args_list
+            if c[0][0][:2] == ["git", "checkout"]
+        ]
+        assert len(checkout_calls) >= 1
+        assert "develop" in checkout_calls[0][0][0]
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_clone_failure_raises(self, mock_run, tmp_path):
+        from devs_common.exceptions import DevsError
+
+        mock_run.return_value = Mock(returncode=1, stdout="", stderr="fatal: repo not found")
+        cache = RepoCache(cache_dir=tmp_path)
+
+        with pytest.raises(DevsError, match="Failed to clone"):
+            cache.ensure_repo("bad/repo")
+
+    def test_get_repo_path(self, tmp_path):
+        cache = RepoCache(cache_dir=tmp_path)
+        assert cache.get_repo_path("ideonate/devs") == tmp_path / "ideonate-devs"
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_default_branches_preference(self, mock_run, tmp_path):
+        """When default_branches is set, those branches are tried in order."""
+        cache = RepoCache(cache_dir=tmp_path, default_branches=["dev", "main"])
+        mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+
+        cache.ensure_repo("org/repo")
+
+        # After clone, should try checkout of first preferred branch (dev)
+        checkout_calls = [
+            c for c in mock_run.call_args_list
+            if len(c[0][0]) >= 2 and c[0][0][:2] == ["git", "checkout"]
+        ]
+        assert len(checkout_calls) >= 1
+        assert "dev" in checkout_calls[0][0][0]
+
+    @patch("devs_common.utils.repo_cache.subprocess.run")
+    def test_clean_runs_git_clean(self, mock_run, tmp_path):
+        """When clean=True, git clean -fd is run after checkout."""
+        cache = RepoCache(cache_dir=tmp_path, clean=True, default_branches=["main"])
+        mock_run.return_value = Mock(returncode=0, stdout="", stderr="")
+
+        cache.ensure_repo("org/repo")
+
+        clean_calls = [
+            c for c in mock_run.call_args_list
+            if len(c[0][0]) >= 2 and c[0][0][:2] == ["git", "clean"]
+        ]
+        assert len(clean_calls) >= 1
+
+
+class TestRepoCliOption:
+    """Test the --repo CLI option integration."""
+
+    @patch("devs.cli.RepoCache")
+    @patch("devs.cli.ContainerManager")
+    @patch("devs.cli.WorkspaceManager")
+    @patch("devs.cli.Project")
+    def test_start_with_repo_flag(self, mock_project_cls, mock_wm, mock_cm, mock_rc):
+        from devs.cli import cli
+
+        # Set up mocks
+        mock_cache_instance = MagicMock()
+        mock_cache_instance.ensure_repo.return_value = Path("/tmp/cache/org-repo")
+        mock_rc.return_value = mock_cache_instance
+
+        mock_project = MagicMock()
+        mock_project.info.name = "org-repo"
+        mock_project_cls.return_value = mock_project
+
+        mock_cm_instance = MagicMock()
+        mock_cm_instance.ensure_container_running.return_value = True
+        mock_cm.return_value = mock_cm_instance
+
+        mock_wm_instance = MagicMock()
+        mock_wm_instance.create_workspace.return_value = Path("/tmp/ws/org-repo-dev1")
+        mock_wm.return_value = mock_wm_instance
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--repo", "org/repo", "start", "dev1"])
+
+        # RepoCache should have been created and called
+        mock_rc.assert_called_once()
+        mock_cache_instance.ensure_repo.assert_called_once_with("org/repo")
+        # Project should have been created with the cached repo path
+        mock_project_cls.assert_called_with(project_dir=Path("/tmp/cache/org-repo"))
+
+    @patch("devs.cli.Project")
+    def test_start_without_repo_flag_uses_cwd(self, mock_project_cls):
+        """Without --repo, Project() is called with no args (uses CWD)."""
+        from devs.cli import cli
+
+        mock_project = MagicMock()
+        mock_project.info.name = "test-project"
+        mock_project_cls.return_value = mock_project
+
+        runner = CliRunner()
+        # Will fail because of missing ContainerManager etc, but we check Project was called correctly
+        with patch("devs.cli.ContainerManager") as mock_cm, \
+             patch("devs.cli.WorkspaceManager") as mock_wm:
+            mock_cm_instance = MagicMock()
+            mock_cm_instance.ensure_container_running.return_value = True
+            mock_cm.return_value = mock_cm_instance
+            mock_wm_instance = MagicMock()
+            mock_wm_instance.create_workspace.return_value = Path("/tmp/ws")
+            mock_wm.return_value = mock_wm_instance
+
+            result = runner.invoke(cli, ["start", "dev1"])
+
+        # Project should be called without project_dir (defaults to CWD)
+        mock_project_cls.assert_called_with()