collab-runtime 0.2.9__py3-none-any.whl

tests/backend/functional/test_package_imports.py

@@ -0,0 +1,43 @@
+"""Unit tests for package imports and basic module availability.
+
+Tests verify that all critical modules can be imported and instantiated without errors.
+This is a basic sanity check for package structure.
+"""
+
+from __future__ import annotations
+
+
+def test_lock_client_import() -> None:
+    """Verify LockClient module can be imported."""
+    from src.lock_client import LockClient  # noqa: F401
+
+
+def test_main_module_import() -> None:
+    """Verify main module can be imported."""
+    from src import main  # noqa: F401
+
+
+def test_live_locks_watcher_import() -> None:
+    """Verify live_locks_watcher module can be imported."""
+    from src import live_locks_watcher  # noqa: F401
+
+
+def test_logging_config_import() -> None:
+    """Verify logging_config module can be imported."""
+    from src import logging_config  # noqa: F401
+
+
+def test_lock_client_instantiation() -> None:
+    """Verify LockClient can be instantiated in test mode."""
+    from src.lock_client import LockClient
+
+    # Should not crash; connection errors are acceptable
+    try:
+        client = LockClient(local_only=True)
+        assert client is not None
+    except Exception as exc:
+        # Connection errors expected in CI; import/instantiation is verified
+        assert any(
+            word in str(exc).lower()
+            for word in ["connect", "supabase", "timeout", "network"]
+        )

tests/backend/integration/test_cli_contract_parity.py

@@ -0,0 +1,220 @@
+"""Integration tests for CLI command contract parity — Phase 1 exit criteria.
+
+These tests verify that the collab package's CLI command surface behaves
+consistently across all invocation patterns and matches expected output formats.
+
+Tests validate:
+- Command availability and exit codes
+- CLI help and documentation
+- Backward compatibility invocation patterns
+- Safe command behavior in test environments
+
+No behavior deltas are acceptable for Phase 1 exit criteria.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+
+def run_collab_cli(*args: str, expect_success: bool = True) -> tuple[int, str, str]:
+    """Execute collab CLI via python -m collab.__main__ and capture results.
+
+    IMPORTANT: Runs in a fully isolated environment so destructive commands
+    (release-all, cleanup, etc.) never touch the real Supabase database.
+
+    Args:
+        *args: Command arguments (e.g., "active", "status", "file.py")
+        expect_success: If True, assert exit code is 0
+
+    Returns:
+        Tuple of (exit_code, stdout, stderr)
+    """
+    cmd = [sys.executable, "-m", "collab.__main__"] + list(args)
+
+    # Build an isolated env that prevents the subprocess from hitting
+    # real Supabase even if it re-loads .env (python-dotenv's load_dotenv
+    # does NOT override pre-existing env vars by default).
+    isolated_env = os.environ.copy()
+    isolated_env.update(
+        {
+            "COLLAB_TEST_MODE": "1",
+            "SUPABASE_URL": "http://localhost:54321",
+            "SUPABASE_ANON_KEY": "test-anon-key-integration",
+            "COLLAB_SILENT_DAEMON": "1",
+            "COLLAB_AUTO_START_WATCHER": "0",
+        }
+    )
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        cwd=".",
+        env=isolated_env,
+    )
+
+    if expect_success and result.returncode != 0:
+        pytest.fail(
+            f"Command failed unexpectedly: {' '.join(cmd)}\n"
+            f"Exit code: {result.returncode}\n"
+            f"stdout: {result.stdout}\n"
+            f"stderr: {result.stderr}"
+        )
+
+    return result.returncode, result.stdout, result.stderr
+
+
+class TestCLICommandAvailability:
+    """Verify all golden commands are available and respond correctly."""
+
+    def test_help_command_succeeds(self) -> None:
+        """Verify --help produces usage information."""
+        exit_code, stdout, _ = run_collab_cli("--help")
+        assert exit_code == 0
+        assert "usage" in stdout.lower() or "collab" in stdout.lower()
+
+    def test_active_command_available(self) -> None:
+        """Verify 'active' command is available and returns valid output."""
+        exit_code, stdout, _ = run_collab_cli("active")
+        assert exit_code == 0
+        # Output should indicate lock status (even if empty)
+        assert len(stdout) > 0
+
+    def test_status_command_accepts_file_argument(self) -> None:
+        """Verify 'status' command accepts file path argument."""
+        exit_code, stdout, _ = run_collab_cli("status", "example.py")
+        assert exit_code == 0
+        assert len(stdout) > 0
+
+    def test_history_command_available(self) -> None:
+        """Verify 'history' command returns valid output."""
+        exit_code, stdout, _ = run_collab_cli("history")
+        assert exit_code == 0
+        assert len(stdout) > 0
+
+    def test_daemon_status_command_available(self) -> None:
+        """Verify 'daemon-status' command is available."""
+        exit_code, _, _ = run_collab_cli(
+            "daemon-status",
+            expect_success=False,
+        )
+        # Exit code can be 0 (running) or 1 (not running); both are valid
+        assert exit_code in (0, 1)
+
+    def test_cleanup_command_available(self) -> None:
+        """Verify 'cleanup' command is available and safe."""
+        exit_code, _, _ = run_collab_cli(
+            "cleanup",
+            expect_success=False,
+        )
+        # Cleanup should not crash even if no processes exist
+        assert exit_code in (0, 1)
+
+    def test_help_documents_golden_commands(self) -> None:
+        """Verify help output documents all primary commands."""
+        _, help_output, _ = run_collab_cli("--help")
+
+        expected_commands = [
+            "acquire",
+            "release",
+            "active",
+            "status",
+            "daemon-start",
+            "daemon-stop",
+            "daemon-status",
+            "history",
+            "reconcile",
+        ]
+
+        for cmd in expected_commands:
+            assert cmd in help_output, f"Command '{cmd}' not found in help output"
+
+
+class TestBackwardCompatibilityInvocation:
+    """Verify all documented invocation patterns work identically."""
+
+    def test_python_m_collab_main_entrypoint(self) -> None:
+        """Verify 'python -m collab.__main__' invocation works."""
+        exit_code, stdout, _ = run_collab_cli("--help")
+        assert exit_code == 0
+        assert len(stdout) > 0
+
+    def test_run_py_entrypoint(self) -> None:
+        """Verify 'python run.py' backward compatibility entrypoint."""
+        result = subprocess.run(
+            [sys.executable, "run.py", "--help"],
+            capture_output=True,
+            text=True,
+            cwd=".",
+        )
+        assert result.returncode == 0
+        assert len(result.stdout) > 0
+
+    def test_collab_console_script_exists(self) -> None:
+        """Verify 'collab' console script is registered in package."""
+        # Check pyproject.toml registration
+        with open("pyproject.toml") as f:
+            content = f.read()
+            assert 'collab = "src.lock_client:main"' in content
+
+
+class TestCLICommandVariants:
+    """Verify specific command patterns work as expected."""
+
+    @pytest.mark.parametrize(
+        "command,expected_exit_success",
+        [
+            (["active"], True),
+            (["status", "dummy_file.py"], True),
+            (["history", "--limit", "5"], True),
+            (["release-all"], True),
+            (["cleanup"], True),
+        ],
+    )
+    def test_command_execution_patterns(
+        self, command: list[str], expected_exit_success: bool
+    ) -> None:
+        """Verify command execution patterns return expected exit codes."""
+        exit_code, _, _ = run_collab_cli(
+            *command,
+            expect_success=expected_exit_success,
+        )
+
+        if expected_exit_success:
+            assert exit_code == 0
+        else:
+            # Should exit cleanly even if it fails
+            assert exit_code in (0, 1, 2)
+
+    def test_invalid_command_fails_gracefully(self) -> None:
+        """Verify invalid commands fail with meaningful exit codes."""
+        exit_code, _, stderr = run_collab_cli(
+            "nonexistent-command",
+            expect_success=False,
+        )
+        # Should fail (non-zero exit) with error output
+        assert exit_code != 0
+        assert len(stderr) > 0 or len(stderr) == 0  # Either way is OK
+
+
+class TestCLIDashboardAssetIntegrity:
+    """Verify dashboard assets are properly bundled in package."""
+
+    def test_dashboard_index_html_exists(self) -> None:
+        """Verify dashboard HTML asset is present."""
+        dashboard_path = os.path.join("src", "dashboard", "index.html")
+        assert os.path.exists(
+            dashboard_path
+        ), f"Dashboard not found at {dashboard_path}"
+
+    def test_dashboard_command_available(self) -> None:
+        """Verify dashboard command is registered."""
+        _, help_output, _ = run_collab_cli("--help")
+        assert "dashboard" in help_output.lower()

tests/backend/unit/live_locks_watcher/__init__.py

@@ -0,0 +1,5 @@
+"""Package marker for live_locks_watcher unit tests.
+
+This allows tests in this directory to use relative imports like `from ._helpers import
+load_watcher_module`.
+"""

tests/backend/unit/live_locks_watcher/_helpers.py

@@ -0,0 +1,123 @@
+"""Helpers for live_locks_watcher tests.
+
+Provide a stable loader that imports the watcher module from `src` and ensures optional
+imports are mocked so tests don't fail at import-time when running in CI without
+optional deps.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from unittest import mock
+
+# Mock optional external modules that the watcher may import at module load
+# time to avoid ImportError / SystemExit during tests.
+sys.modules.setdefault("supabase", mock.MagicMock())
+sys.modules.setdefault("plyer", mock.MagicMock())
+
+
+def _find_repo_root() -> Path:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "pyproject.toml").exists() and (parent / "src").exists():
+            return parent
+    raise FileNotFoundError("Could not locate repository root")
+
+
+def load_watcher_module():
+    proj_root = _find_repo_root()
+    module_path = proj_root / "src" / "live_locks_watcher.py"
+    mod_name = "src.live_locks_watcher"
+    # If already loaded, return the cached module but reset volatile
+    # module-level state so tests execute with predictable defaults.
+    # Many tests expect the same module *instance* (a `watcher` variable
+    # created at import-time), while also needing fresh global state
+    # between test invocations. Reset known mutable globals here.
+    if mod_name in sys.modules:
+        mod = sys.modules[mod_name]
+        for _attr, _val in (
+            ("_shutdown_done", False),
+            ("_local_owned_locks", set()),
+            ("_active_conflicts", set()),
+            ("_warned_remote_locks", set()),
+            ("_known_remote_locks", set()),
+            ("SESSION_TOKEN", ""),
+            ("_dashboard_url", None),
+            ("_dashboard_server", None),
+            ("_dashboard_thread", None),
+        ):
+            try:
+                setattr(mod, _attr, _val)
+            except Exception:
+                pass
+        # Use a test-local PID file to avoid colliding with any real watcher
+        # running on the developer machine or CI environment.
+        try:
+            tmp_pid_name = f"pytest_collab_{os.getpid()}.daemon.pid"
+            tmp_pid = os.path.join(tempfile.gettempdir(), tmp_pid_name)
+            setattr(mod, "PID_FILE", tmp_pid)
+        except Exception:
+            pass
+        # Use a test-local isolated .collab root to avoid touching repo files.
+        try:
+            tmp_collab_dir = os.path.join(
+                tempfile.gettempdir(), f"pytest_collab_{os.getpid()}_collab"
+            )
+            os.makedirs(tmp_collab_dir, exist_ok=True)
+            # Mirror the real dashboard template into the test collab root
+            try:
+                repo_dashboard = Path(proj_root) / "src" / "dashboard"
+                if repo_dashboard.exists():
+                    shutil.copytree(
+                        str(repo_dashboard),
+                        os.path.join(tmp_collab_dir, "dashboard"),
+                        dirs_exist_ok=True,
+                    )
+            except Exception:
+                pass
+            setattr(mod, "_COLLAB_ROOT", tmp_collab_dir)
+        except Exception:
+            pass
+        return mod
+
+    spec = importlib.util.spec_from_file_location(mod_name, str(module_path))
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    # Insert into sys.modules early so recursive imports / monkeypatching
+    # that reference the module name get the same instance.
+    sys.modules[mod_name] = mod
+    spec.loader.exec_module(mod)  # type: ignore[attr-defined]
+    # Also set a test-local PID file by default to avoid false positives when
+    # detecting existing watcher processes on the developer machine.
+    try:
+        tmp_pid_name = f"pytest_collab_{os.getpid()}.daemon.pid"
+        tmp_pid = os.path.join(tempfile.gettempdir(), tmp_pid_name)
+        setattr(mod, "PID_FILE", tmp_pid)
+    except Exception:
+        pass
+    # Use a test-local isolated .collab root so tests don't modify repo files.
+    try:
+        tmp_collab_dir = os.path.join(
+            tempfile.gettempdir(), f"pytest_collab_{os.getpid()}_collab"
+        )
+        os.makedirs(tmp_collab_dir, exist_ok=True)
+        # Mirror the real dashboard template into the test collab root
+        try:
+            repo_dashboard = Path(proj_root) / "src" / "dashboard"
+            if repo_dashboard.exists():
+                shutil.copytree(
+                    str(repo_dashboard),
+                    os.path.join(tmp_collab_dir, "dashboard"),
+                    dirs_exist_ok=True,
+                )
+        except Exception:
+            pass
+        setattr(mod, "_COLLAB_ROOT", tmp_collab_dir)
+    except Exception:
+        pass
+    return mod

tests/backend/unit/live_locks_watcher/conftest.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from ._helpers import load_watcher_module
+
+
+@pytest.fixture(autouse=True)
+def isolate_collab(monkeypatch, tmp_path):
+    """Autouse fixture: ensure the watcher module uses a test-local `.collab` root and
+    PID file so tests cannot accidentally modify repository files."""
+    mod = load_watcher_module()
+    monkeypatch.setattr(mod, "_COLLAB_ROOT", str(tmp_path))
+    pid = tmp_path / f"pytest_collab_{os.getpid()}.daemon.pid"
+    monkeypatch.setattr(mod, "PID_FILE", str(pid))
+    yield

tests/backend/unit/live_locks_watcher/test_live_locks_watcher_dashboard.py

@@ -0,0 +1,188 @@
+"""Dashboard and server-start tests for live_locks_watcher."""
+
+from __future__ import annotations
+
+from ._helpers import load_watcher_module
+
+
+def test_start_dashboard_server_returns_url(monkeypatch):
+    mod = load_watcher_module()
+    import http.server
+
+    monkeypatch.setattr(mod, "SUPABASE_URL", "https://test.supabase.co")
+    monkeypatch.setattr(mod, "SUPABASE_ANON_KEY", "test_key")
+    monkeypatch.setattr(mod, "SUPABASE_SERVICE_ROLE_KEY", None)
+    monkeypatch.setattr(mod, "DEVELOPER_ID", "alice")
+
+    class FakeServer:
+        def __init__(self, addr, handler):
+            self.server_address = (addr[0], 9999)
+
+        def serve_forever(self):
+            pass
+
+        def shutdown(self):
+            pass
+
+    monkeypatch.setattr(http.server, "ThreadingHTTPServer", FakeServer)
+
+    url = mod._start_dashboard_server()
+    assert url is not None
+    assert url.startswith("http://127.0.0.1:9999/")
+    assert url.endswith(".html")
+
+
+def test_start_dashboard_server_missing_html(monkeypatch):
+    mod = load_watcher_module()
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", "/nonexistent/path")
+    result = mod._start_dashboard_server()
+    assert result is None
+
+
+def test_start_dashboard_server_read_error(monkeypatch, tmp_path):
+    mod = load_watcher_module()
+    dashboard_dir = tmp_path / "dashboard"
+    dashboard_dir.mkdir()
+    html_file = dashboard_dir / "index.html"
+    html_file.write_text("test")
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_path))
+
+    original_open = open
+
+    def failing_open(path, *args, **kwargs):
+        if "index.html" in str(path):
+            raise PermissionError("denied")
+        return original_open(path, *args, **kwargs)
+
+    monkeypatch.setattr("builtins.open", failing_open)
+    result = mod._start_dashboard_server()
+    assert result is None
+
+
+def test_start_dashboard_server_http_server_error(monkeypatch, tmp_path):
+    mod = load_watcher_module()
+    import http.server
+
+    dashboard_dir = tmp_path / "dashboard"
+    dashboard_dir.mkdir()
+    (dashboard_dir / "index.html").write_text("<html></html>")
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_path))
+    monkeypatch.setattr(mod, "SUPABASE_URL", "https://test.supabase.co")
+    monkeypatch.setattr(mod, "SUPABASE_ANON_KEY", "key")
+    monkeypatch.setattr(mod, "DEVELOPER_ID", "alice")
+
+    def raising_server(*args, **kwargs):
+        raise OSError("Address already in use")
+
+    monkeypatch.setattr(http.server, "ThreadingHTTPServer", raising_server)
+
+    result = mod._start_dashboard_server()
+    assert result is None
+
+
+def test_start_dashboard_server_migrated(tmp_path, monkeypatch):
+    mod = load_watcher_module()
+    # Prepare dashboard directory
+    d = tmp_path / "dashboard"
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "index.html").write_text("<html>ok</html>")
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_path))
+
+    # Monkeypatch the ThreadingHTTPServer to avoid binding sockets
+    import http.server as _http
+    import threading as _threading
+
+    class FakeServer:
+        def __init__(self, addr, handler):
+            self.server_address = ("127.0.0.1", 11111)
+
+        def serve_forever(self):
+            return None
+
+        def shutdown(self):
+            return None
+
+    class FakeThread:
+        def __init__(self, target, daemon=True):
+            self._target = target
+
+        def start(self):
+            return None
+
+    monkeypatch.setattr(_http, "ThreadingHTTPServer", FakeServer)
+    monkeypatch.setattr(_threading, "Thread", FakeThread)
+
+    url = mod._start_dashboard_server()
+    assert url is not None
+
+
+def test_start_dashboard_server_tmpfile_error(monkeypatch, tmp_path):
+    mod = load_watcher_module()
+    import tempfile
+
+    dashboard_dir = tmp_path / "dashboard"
+    dashboard_dir.mkdir()
+    (dashboard_dir / "index.html").write_text("<html></html>")
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_path))
+    monkeypatch.setattr(mod, "SUPABASE_URL", "https://test.supabase.co")
+    monkeypatch.setattr(mod, "SUPABASE_ANON_KEY", "key")
+    monkeypatch.setattr(mod, "DEVELOPER_ID", "alice")
+
+    def failing_tmpfile(**kwargs):
+        raise OSError("disk full")
+
+    monkeypatch.setattr(tempfile, "NamedTemporaryFile", failing_tmpfile)
+
+    result = mod._start_dashboard_server()
+    assert result is None
+
+
+def test_start_dashboard_server_unlink_error(monkeypatch, tmp_path):
+    mod = load_watcher_module()
+    import http.server
+
+    dashboard_dir = tmp_path / "dashboard"
+    dashboard_dir.mkdir()
+    (dashboard_dir / "index.html").write_text("<html></html>")
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_path))
+    monkeypatch.setattr(mod, "SUPABASE_URL", "https://test.supabase.co")
+    monkeypatch.setattr(mod, "SUPABASE_ANON_KEY", "key")
+    monkeypatch.setattr(mod, "DEVELOPER_ID", "alice")
+
+    def raising_server(*args, **kwargs):
+        raise OSError("port in use")
+
+    monkeypatch.setattr(http.server, "ThreadingHTTPServer", raising_server)
+
+    original_unlink = __import__("os").unlink
+
+    def failing_unlink(path):
+        if str(path).endswith(".html"):
+            raise OSError("cannot unlink")
+        return original_unlink(path)
+
+    monkeypatch.setattr(__import__("os"), "unlink", failing_unlink)
+
+    result = mod._start_dashboard_server()
+    assert result is None
+
+
+# ---- Auto-migrated from migrated_remaining ----
+
+
+def test_start_dashboard_server_missing_and_success_moved(tmp_path, monkeypatch):
+    mod = load_watcher_module()
+    tmp_root = tmp_path / "collab_root"
+    (tmp_root / "dashboard").mkdir(parents=True)
+    # missing file
+    monkeypatch.setattr(mod, "_RESOURCE_ROOT", str(tmp_root))
+    url = mod._start_dashboard_server()
+    assert url is None
+
+    # create file and succeed
+    (tmp_root / "dashboard" / "index.html").write_text("<html>ok</html>")
+    url2 = mod._start_dashboard_server()
+    assert url2 and url2.startswith("http://127.0.0.1:")
+
+
+watcher = load_watcher_module()

tests/backend/unit/live_locks_watcher/test_live_locks_watcher_developer.py

@@ -0,0 +1,56 @@
+"""Developer identity tests for live_locks_watcher."""
+
+from __future__ import annotations
+
+import subprocess
+
+from ._helpers import load_watcher_module
+
+
+def test_get_developer_id_from_env(monkeypatch):
+    mod = load_watcher_module()
+    # Force git to fail and ensure environment fallback is used
+    monkeypatch.setenv("USERNAME", "test_developer")
+
+    def mock_check_output(cmd, *a, **k):
+        raise subprocess.CalledProcessError(1, cmd)
+
+    monkeypatch.setattr(subprocess, "check_output", mock_check_output)
+
+    result = mod._get_developer_id()
+    assert result == "test_developer"
+
+
+def test_get_developer_id_from_git(monkeypatch):
+    mod = load_watcher_module()
+    monkeypatch.delenv("DEVELOPER_ID", raising=False)
+
+    def mock_check_output(cmd, *a, **k):
+        if "user.name" in cmd:
+            return b"git_user\n"
+        raise subprocess.CalledProcessError(1, cmd)
+
+    monkeypatch.setattr(subprocess, "check_output", mock_check_output)
+
+    result = mod._get_developer_id()
+    assert result == "git_user"
+
+
+# ---- Auto-migrated from migrated_remaining ----
+
+
+def test_is_ephemeral_dev_empty():
+    mod = load_watcher_module()
+    # Cover the branch where dev_id is falsy and returns False
+    assert mod._is_ephemeral_dev("") is False
+
+
+def test_is_ephemeral_dev_matches_prefix():
+    """_is_ephemeral_dev returns True when dev_id starts with an ephemeral prefix."""
+    mod = load_watcher_module()
+    assert mod._is_ephemeral_dev("test_dev_42") is True
+    assert mod._is_ephemeral_dev("ci-runner") is True
+    assert mod._is_ephemeral_dev("regular_user") is False
+
+
+watcher = load_watcher_module()