@pennyfarthing/core 10.2.0 → 10.3.0

package/pennyfarthing_scripts/tests/test_bikerack.py

@@ -0,0 +1,785 @@
+"""Tests for BikeRack launcher CLI.
+
+Story 101-5: BikeRack launcher CLI (pf bikerack start/stop/status)
+Epic: 101 — BikeRack Mode (ADR-0024)
+
+Acceptance Criteria:
+- [AC1]  `pf bikerack start` starts WheelHub background with IS_BIKERACK=1
+- [AC2]  Polls for .bikerack-port file (100ms interval, 5s timeout)
+- [AC3]  Sets exactly 5 OTEL env vars from discovered port (Rule 5)
+- [AC4]  Uses exec (not spawn) for Claude CLI (CE-4)
+- [AC5]  trap EXIT registered before exec to kill WheelHub PID (Rule 8)
+- [AC6]  Writes .bikerack-pid after spawning WheelHub
+- [AC7]  `pf bikerack stop` reads PID, sends SIGTERM, deletes files
+- [AC8]  `pf bikerack status` shows running state (PID, port, uptime)
+- [AC9]  Error if already running (.bikerack-port exists with live PID)
+- [AC10] Exit code 1 if WheelHub fails to start, 2 if already running
+- [AC11] Prints dashboard URL on startup
+- [AC12] `just bikerack` works as alias
+
+Tests should FAIL until launcher.py is implemented.
+"""
+
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from pennyfarthing_scripts.bikerack.launcher import (
+    build_otel_env,
+    cleanup_files,
+    exec_claude,
+    get_status,
+    is_already_running,
+    is_process_alive,
+    poll_for_port_file,
+    read_pid_file,
+    read_port_file,
+    register_cleanup,
+    start_wheelhub,
+    stop_bikerack,
+    write_pid_file,
+)
+
+# ---------------------------------------------------------------------------
+# AC1: `pf bikerack start` starts WheelHub background with IS_BIKERACK=1
+# ---------------------------------------------------------------------------
+
+
+class TestStartWheelHub:
+    """AC1: start_wheelhub starts WheelHub in background with IS_BIKERACK=1."""
+
+    def test_starts_subprocess(self, tmp_path: Path) -> None:
+        """start_wheelhub should return a Popen object (background process)."""
+        with patch("pennyfarthing_scripts.bikerack.launcher.subprocess.Popen") as mock_popen:
+            mock_proc = MagicMock()
+            mock_proc.pid = 12345
+            mock_popen.return_value = mock_proc
+
+            result = start_wheelhub(tmp_path)
+
+            assert result.pid == 12345
+            mock_popen.assert_called_once()
+
+    def test_sets_is_bikerack_env(self, tmp_path: Path) -> None:
+        """start_wheelhub should set IS_BIKERACK=1 in subprocess env."""
+        with patch("pennyfarthing_scripts.bikerack.launcher.subprocess.Popen") as mock_popen:
+            mock_popen.return_value = MagicMock(pid=12345)
+
+            start_wheelhub(tmp_path)
+
+            # Inspect the env passed to Popen
+            popen_kwargs = mock_popen.call_args
+            env = popen_kwargs.kwargs.get("env") or popen_kwargs[1].get("env")
+            assert env is not None, "Popen should be called with env parameter"
+            assert env.get("IS_BIKERACK") == "1"
+
+    def test_sets_project_dir_env(self, tmp_path: Path) -> None:
+        """start_wheelhub should set CYCLIST_PROJECT_DIR in subprocess env."""
+        with patch("pennyfarthing_scripts.bikerack.launcher.subprocess.Popen") as mock_popen:
+            mock_popen.return_value = MagicMock(pid=12345)
+
+            start_wheelhub(tmp_path)
+
+            popen_kwargs = mock_popen.call_args
+            env = popen_kwargs.kwargs.get("env") or popen_kwargs[1].get("env")
+            assert env.get("CYCLIST_PROJECT_DIR") == str(tmp_path)
+
+    def test_process_is_background(self, tmp_path: Path) -> None:
+        """start_wheelhub should not block (background process)."""
+        with patch("pennyfarthing_scripts.bikerack.launcher.subprocess.Popen") as mock_popen:
+            mock_popen.return_value = MagicMock(pid=12345)
+
+            result = start_wheelhub(tmp_path)
+
+            # Should return immediately (Popen, not run)
+            result.wait.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# AC2: Polls for .bikerack-port file (100ms interval, 5s timeout)
+# ---------------------------------------------------------------------------
+
+
+class TestPortFilePolling:
+    """AC2: poll_for_port_file polls with correct interval and timeout."""
+
+    def test_returns_port_when_file_exists(self, tmp_path: Path) -> None:
+        """poll_for_port_file should return port number from file."""
+        port_file = tmp_path / ".bikerack-port"
+        port_file.write_text("2898")
+
+        result = poll_for_port_file(tmp_path)
+
+        assert result == 2898
+
+    def test_raises_on_timeout(self, tmp_path: Path) -> None:
+        """poll_for_port_file should raise TimeoutError when file never appears."""
+        # No port file exists — should timeout
+        with pytest.raises(TimeoutError):
+            poll_for_port_file(tmp_path, timeout=0.3, interval=0.1)
+
+    def test_waits_for_file_to_appear(self, tmp_path: Path) -> None:
+        """poll_for_port_file should poll until file appears."""
+        port_file = tmp_path / ".bikerack-port"
+
+        # Simulate file appearing after short delay
+        call_count = [0]
+        original_exists = Path.exists
+
+        def delayed_exists(self_path):
+            if str(self_path) == str(port_file):
+                call_count[0] += 1
+                if call_count[0] >= 3:
+                    port_file.write_text("2898")
+                    return True
+                return False
+            return original_exists(self_path)
+
+        with patch.object(Path, "exists", delayed_exists):
+            result = poll_for_port_file(tmp_path, timeout=5.0, interval=0.05)
+            assert result == 2898
+
+    def test_default_timeout_is_5_seconds(self, tmp_path: Path) -> None:
+        """poll_for_port_file default timeout should be 5 seconds."""
+        import inspect
+
+        sig = inspect.signature(poll_for_port_file)
+        assert sig.parameters["timeout"].default == 5.0
+
+    def test_default_interval_is_100ms(self, tmp_path: Path) -> None:
+        """poll_for_port_file default interval should be 0.1 seconds (100ms)."""
+        import inspect
+
+        sig = inspect.signature(poll_for_port_file)
+        assert sig.parameters["interval"].default == 0.1
+
+    def test_reads_integer_port(self, tmp_path: Path) -> None:
+        """poll_for_port_file should parse port as integer."""
+        port_file = tmp_path / ".bikerack-port"
+        port_file.write_text("3000\n")  # Trailing newline should be handled
+
+        result = poll_for_port_file(tmp_path)
+
+        assert isinstance(result, int)
+        assert result == 3000
+
+
+# ---------------------------------------------------------------------------
+# AC3: Sets exactly 5 OTEL env vars from discovered port (Rule 5)
+# ---------------------------------------------------------------------------
+
+
+class TestOtelEnvVars:
+    """AC3: build_otel_env sets exactly 5 OTEL env vars (Rule 5 from ADR-0024)."""
+
+    def test_returns_exactly_five_vars(self) -> None:
+        """build_otel_env should return exactly 5 environment variables."""
+        result = build_otel_env(2898)
+        assert len(result) == 5, f"Expected 5 OTEL vars, got {len(result)}: {list(result.keys())}"
+
+    def test_includes_telemetry_enable(self) -> None:
+        """build_otel_env should include CLAUDE_CODE_ENABLE_TELEMETRY=1."""
+        result = build_otel_env(2898)
+        assert result.get("CLAUDE_CODE_ENABLE_TELEMETRY") == "1"
+
+    def test_includes_logs_exporter(self) -> None:
+        """build_otel_env should include OTEL_LOGS_EXPORTER=otlp."""
+        result = build_otel_env(2898)
+        assert result.get("OTEL_LOGS_EXPORTER") == "otlp"
+
+    def test_includes_metrics_exporter(self) -> None:
+        """build_otel_env should include OTEL_METRICS_EXPORTER=otlp."""
+        result = build_otel_env(2898)
+        assert result.get("OTEL_METRICS_EXPORTER") == "otlp"
+
+    def test_includes_otlp_protocol(self) -> None:
+        """build_otel_env should include OTEL_EXPORTER_OTLP_PROTOCOL=http/json."""
+        result = build_otel_env(2898)
+        assert result.get("OTEL_EXPORTER_OTLP_PROTOCOL") == "http/json"
+
+    def test_includes_otlp_endpoint_with_port(self) -> None:
+        """build_otel_env should include OTEL_EXPORTER_OTLP_ENDPOINT with correct port."""
+        result = build_otel_env(2898)
+        assert result.get("OTEL_EXPORTER_OTLP_ENDPOINT") == "http://localhost:2898"
+
+    def test_endpoint_uses_provided_port(self) -> None:
+        """build_otel_env endpoint should use the port argument."""
+        result = build_otel_env(3456)
+        assert result["OTEL_EXPORTER_OTLP_ENDPOINT"] == "http://localhost:3456"
+
+    def test_no_traces_exporter(self) -> None:
+        """build_otel_env should NOT include OTEL_TRACES_EXPORTER (Claude doesn't emit traces)."""
+        result = build_otel_env(2898)
+        assert "OTEL_TRACES_EXPORTER" not in result
+
+    def test_returns_dict_of_strings(self) -> None:
+        """build_otel_env should return dict[str, str]."""
+        result = build_otel_env(2898)
+        for key, val in result.items():
+            assert isinstance(key, str), f"Key {key!r} is not str"
+            assert isinstance(val, str), f"Value {val!r} for {key} is not str"
+
+
+# ---------------------------------------------------------------------------
+# AC4: Uses exec (not spawn) for Claude CLI (CE-4)
+# ---------------------------------------------------------------------------
+
+
+class TestExecClaude:
+    """AC4: exec_claude replaces the process with Claude CLI via os.execvpe."""
+
+    def test_calls_os_execvpe(self) -> None:
+        """exec_claude should call os.execvpe (not subprocess.Popen)."""
+        otel_env = build_otel_env(2898)
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.execvpe") as mock_exec:
+            # execvpe never returns, so mock it
+            mock_exec.side_effect = SystemExit(0)
+
+            with pytest.raises(SystemExit):
+                exec_claude(otel_env)
+
+            mock_exec.assert_called_once()
+
+    def test_execs_claude_binary(self) -> None:
+        """exec_claude should exec the 'claude' binary."""
+        otel_env = build_otel_env(2898)
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.execvpe") as mock_exec:
+            mock_exec.side_effect = SystemExit(0)
+
+            with pytest.raises(SystemExit):
+                exec_claude(otel_env)
+
+            args = mock_exec.call_args
+            # First arg to execvpe is the program name
+            assert args[0][0] == "claude"
+
+    def test_merges_otel_env_with_current_env(self) -> None:
+        """exec_claude should merge OTEL vars into current environment."""
+        otel_env = {"CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_LOGS_EXPORTER": "otlp"}
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.execvpe") as mock_exec:
+            mock_exec.side_effect = SystemExit(0)
+
+            with pytest.raises(SystemExit):
+                exec_claude(otel_env)
+
+            args = mock_exec.call_args
+            # Third arg is the env dict
+            exec_env = args[0][2] if len(args[0]) > 2 else args.kwargs.get("env")
+            assert exec_env is not None
+            # Should contain OTEL vars
+            assert exec_env.get("CLAUDE_CODE_ENABLE_TELEMETRY") == "1"
+            # Should also contain existing env vars (e.g., PATH)
+            assert "PATH" in exec_env
+
+    def test_does_not_use_subprocess(self) -> None:
+        """exec_claude must NOT use subprocess (CE-4: exec, not spawn)."""
+        otel_env = build_otel_env(2898)
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.execvpe") as mock_exec:
+            mock_exec.side_effect = SystemExit(0)
+
+            with patch("pennyfarthing_scripts.bikerack.launcher.subprocess.Popen") as mock_popen:
+                with pytest.raises(SystemExit):
+                    exec_claude(otel_env)
+
+                mock_popen.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# AC5: trap EXIT registered before exec to kill WheelHub PID (Rule 8)
+# ---------------------------------------------------------------------------
+
+
+class TestCleanupRegistration:
+    """AC5: register_cleanup sets up atexit handler to kill WheelHub."""
+
+    def test_registers_atexit_handler(self, tmp_path: Path) -> None:
+        """register_cleanup should register an atexit handler."""
+        with patch("pennyfarthing_scripts.bikerack.launcher.atexit.register") as mock_register:
+            register_cleanup(tmp_path, pid=12345)
+
+            mock_register.assert_called_once()
+
+    def test_cleanup_kills_wheelhub_pid(self, tmp_path: Path) -> None:
+        """Registered cleanup should send SIGTERM to WheelHub PID."""
+        cleanup_func = None
+
+        def capture_handler(func, *args, **kwargs):
+            nonlocal cleanup_func
+
+            def _call_cleanup():
+                return func(*args, **kwargs)
+
+            cleanup_func = _call_cleanup
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.atexit.register", side_effect=capture_handler):
+            register_cleanup(tmp_path, pid=12345)
+
+        assert cleanup_func is not None, "atexit handler not registered"
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill") as mock_kill:
+            with patch("pennyfarthing_scripts.bikerack.launcher.os.path.exists", return_value=True):
+                # Simulate cleanup
+                try:
+                    cleanup_func()
+                except (ProcessLookupError, OSError):
+                    pass  # Expected if mocking doesn't cover all paths
+
+                # Should attempt to kill the PID
+                mock_kill.assert_called()
+                kill_args = mock_kill.call_args[0]
+                assert kill_args[0] == 12345
+                assert kill_args[1] == signal.SIGTERM
+
+    def test_cleanup_removes_port_file(self, tmp_path: Path) -> None:
+        """Registered cleanup should delete .bikerack-port file."""
+        port_file = tmp_path / ".bikerack-port"
+        port_file.write_text("2898")
+
+        cleanup_func = None
+
+        def capture_handler(func, *args, **kwargs):
+            nonlocal cleanup_func
+
+            def _call_cleanup():
+                return func(*args, **kwargs)
+
+            cleanup_func = _call_cleanup
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.atexit.register", side_effect=capture_handler):
+            register_cleanup(tmp_path, pid=12345)
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
+            try:
+                cleanup_func()
+            except (ProcessLookupError, OSError):
+                pass
+
+        assert not port_file.exists(), ".bikerack-port should be deleted by cleanup"
+
+    def test_cleanup_removes_pid_file(self, tmp_path: Path) -> None:
+        """Registered cleanup should delete .bikerack-pid file."""
+        pid_file = tmp_path / ".bikerack-pid"
+        pid_file.write_text("12345")
+
+        cleanup_func = None
+
+        def capture_handler(func, *args, **kwargs):
+            nonlocal cleanup_func
+
+            def _call_cleanup():
+                return func(*args, **kwargs)
+
+            cleanup_func = _call_cleanup
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.atexit.register", side_effect=capture_handler):
+            register_cleanup(tmp_path, pid=12345)
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
+            try:
+                cleanup_func()
+            except (ProcessLookupError, OSError):
+                pass
+
+        assert not pid_file.exists(), ".bikerack-pid should be deleted by cleanup"
+
+
+# ---------------------------------------------------------------------------
+# AC6: Writes .bikerack-pid after spawning WheelHub
+# ---------------------------------------------------------------------------
+
+
+class TestPidFile:
+    """AC6: write_pid_file writes .bikerack-pid."""
+
+    def test_writes_pid_to_file(self, tmp_path: Path) -> None:
+        """write_pid_file should write PID as ASCII string."""
+        write_pid_file(tmp_path, pid=48291)
+
+        pid_file = tmp_path / ".bikerack-pid"
+        assert pid_file.exists()
+        assert pid_file.read_text().strip() == "48291"
+
+    def test_read_pid_file_returns_pid(self, tmp_path: Path) -> None:
+        """read_pid_file should return PID as integer."""
+        pid_file = tmp_path / ".bikerack-pid"
+        pid_file.write_text("48291")
+
+        result = read_pid_file(tmp_path)
+
+        assert result == 48291
+
+    def test_read_pid_file_returns_none_when_missing(self, tmp_path: Path) -> None:
+        """read_pid_file should return None when file doesn't exist."""
+        result = read_pid_file(tmp_path)
+
+        assert result is None
+
+    def test_write_pid_creates_file_in_project_dir(self, tmp_path: Path) -> None:
+        """write_pid_file should create .bikerack-pid in project directory."""
+        write_pid_file(tmp_path, pid=99999)
+
+        expected = tmp_path / ".bikerack-pid"
+        assert expected.exists()
+        assert expected.name == ".bikerack-pid"
+
+
+# ---------------------------------------------------------------------------
+# AC7: `pf bikerack stop` reads PID, sends SIGTERM, deletes files
+# ---------------------------------------------------------------------------
+
+
+class TestStopBikeRack:
+    """AC7: stop_bikerack sends SIGTERM and cleans up files."""
+
+    def test_sends_sigterm_to_pid(self, tmp_path: Path) -> None:
+        """stop_bikerack should send SIGTERM to the WheelHub PID."""
+        # Setup: create port and pid files
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill") as mock_kill:
+            with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+                stop_bikerack(tmp_path)
+
+                mock_kill.assert_called_with(12345, signal.SIGTERM)
+
+    def test_deletes_port_file(self, tmp_path: Path) -> None:
+        """stop_bikerack should delete .bikerack-port."""
+        port_file = tmp_path / ".bikerack-port"
+        port_file.write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
+            with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+                stop_bikerack(tmp_path)
+
+        assert not port_file.exists()
+
+    def test_deletes_pid_file(self, tmp_path: Path) -> None:
+        """stop_bikerack should delete .bikerack-pid."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        pid_file = tmp_path / ".bikerack-pid"
+        pid_file.write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
+            with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+                stop_bikerack(tmp_path)
+
+        assert not pid_file.exists()
+
+    def test_returns_success_dict(self, tmp_path: Path) -> None:
+        """stop_bikerack should return {success: True, pid: N, message: str}."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
+            with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+                result = stop_bikerack(tmp_path)
+
+        assert result["success"] is True
+        assert result["pid"] == 12345
+
+    def test_returns_error_when_not_running(self, tmp_path: Path) -> None:
+        """stop_bikerack should return error when no instance is running."""
+        # No port or pid files
+        result = stop_bikerack(tmp_path)
+
+        assert result["success"] is False
+
+
+# ---------------------------------------------------------------------------
+# AC8: `pf bikerack status` shows running state (PID, port, uptime)
+# ---------------------------------------------------------------------------
+
+
+class TestStatus:
+    """AC8: get_status returns running state info."""
+
+    def test_returns_running_state(self, tmp_path: Path) -> None:
+        """get_status should detect running BikeRack."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+            result = get_status(tmp_path)
+
+        assert result["running"] is True
+        assert result["pid"] == 12345
+        assert result["port"] == 2898
+
+    def test_returns_not_running(self, tmp_path: Path) -> None:
+        """get_status should detect no running BikeRack."""
+        result = get_status(tmp_path)
+
+        assert result["running"] is False
+
+    def test_includes_dashboard_url(self, tmp_path: Path) -> None:
+        """get_status should include dashboard URL when running."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+            result = get_status(tmp_path)
+
+        assert "http://localhost:2898/bikerack" in result.get("dashboard", "")
+
+    def test_detects_stale_pid(self, tmp_path: Path) -> None:
+        """get_status should detect stale PID (file exists, process dead)."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("99999")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=False):
+            result = get_status(tmp_path)
+
+        assert result["running"] is False
+
+
+# ---------------------------------------------------------------------------
+# AC9: Error if already running (.bikerack-port exists with live PID)
+# ---------------------------------------------------------------------------
+
+
+class TestAlreadyRunning:
+    """AC9: is_already_running detects existing BikeRack instance."""
+
+    def test_detects_running_instance(self, tmp_path: Path) -> None:
+        """is_already_running should return True when port file + live PID."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+            running, pid, port = is_already_running(tmp_path)
+
+        assert running is True
+        assert pid == 12345
+        assert port == 2898
+
+    def test_not_running_when_no_files(self, tmp_path: Path) -> None:
+        """is_already_running should return False when no files exist."""
+        running, pid, port = is_already_running(tmp_path)
+
+        assert running is False
+        assert pid is None
+        assert port is None
+
+    def test_not_running_when_stale_pid(self, tmp_path: Path) -> None:
+        """is_already_running should return False when PID is dead (stale)."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("99999")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=False):
+            running, pid, port = is_already_running(tmp_path)
+
+        assert running is False
+
+    def test_cleans_stale_files(self, tmp_path: Path) -> None:
+        """is_already_running should clean up stale files when PID is dead."""
+        port_file = tmp_path / ".bikerack-port"
+        pid_file = tmp_path / ".bikerack-pid"
+        port_file.write_text("2898")
+        pid_file.write_text("99999")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=False):
+            is_already_running(tmp_path)
+
+        assert not port_file.exists(), "Stale port file should be cleaned up"
+        assert not pid_file.exists(), "Stale PID file should be cleaned up"
+
+
+# ---------------------------------------------------------------------------
+# AC10: Exit codes — 1 if WheelHub fails to start, 2 if already running
+# ---------------------------------------------------------------------------
+
+
+class TestExitCodes:
+    """AC10: Correct exit codes for error conditions."""
+
+    def test_exit_code_2_when_already_running(self, tmp_path: Path) -> None:
+        """Start should raise SystemExit(2) when already running."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+        (tmp_path / ".bikerack-pid").write_text("12345")
+
+        with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
+            with patch("pennyfarthing_scripts.bikerack.launcher.is_already_running",
+                       return_value=(True, 12345, 2898)):
+                # The start flow should detect already-running and exit 2
+                # This tests the logic, not the full CLI flow
+                running, pid, port = is_already_running(tmp_path)
+                assert running is True
+                # The CLI layer should convert this to exit code 2
+
+
+# ---------------------------------------------------------------------------
+# AC11: Prints dashboard URL on startup
+# ---------------------------------------------------------------------------
+
+
+class TestDashboardUrl:
+    """AC11: Dashboard URL is displayed on startup."""
+
+    def test_dashboard_url_format(self) -> None:
+        """Dashboard URL should be http://localhost:{port}/bikerack."""
+        # The URL format is deterministic from the port
+        port = 2898
+        expected = f"http://localhost:{port}/bikerack"
+        assert expected == "http://localhost:2898/bikerack"
+
+    def test_dashboard_url_uses_custom_port(self) -> None:
+        """Dashboard URL should use the actual discovered port."""
+        port = 3456
+        expected = f"http://localhost:{port}/bikerack"
+        assert expected == "http://localhost:3456/bikerack"
+
+
+# ---------------------------------------------------------------------------
+# AC12: `just bikerack` works as alias (tested at integration level)
+# ---------------------------------------------------------------------------
+
+
+class TestBikeRackCLI:
+    """AC12: CLI module entry point works."""
+
+    def test_bikerack_cli_help(self) -> None:
+        """bikerack CLI should show help with --help."""
+        result = subprocess.run(
+            [sys.executable, "-m", "pennyfarthing_scripts.bikerack", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            cwd=str(Path(__file__).parent.parent.parent),
+        )
+
+        assert result.returncode == 0
+        assert "bikerack" in result.stdout.lower() or "BikeRack" in result.stdout
+
+    def test_bikerack_has_start_subcommand(self) -> None:
+        """bikerack CLI should have start subcommand."""
+        result = subprocess.run(
+            [sys.executable, "-m", "pennyfarthing_scripts.bikerack", "start", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            cwd=str(Path(__file__).parent.parent.parent),
+        )
+
+        assert result.returncode == 0
+
+    def test_bikerack_has_stop_subcommand(self) -> None:
+        """bikerack CLI should have stop subcommand."""
+        result = subprocess.run(
+            [sys.executable, "-m", "pennyfarthing_scripts.bikerack", "stop", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            cwd=str(Path(__file__).parent.parent.parent),
+        )
+
+        assert result.returncode == 0
+
+    def test_bikerack_has_status_subcommand(self) -> None:
+        """bikerack CLI should have status subcommand."""
+        result = subprocess.run(
+            [sys.executable, "-m", "pennyfarthing_scripts.bikerack", "status", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            cwd=str(Path(__file__).parent.parent.parent),
+        )
+
+        assert result.returncode == 0
+
+    def test_bikerack_default_invokes_start(self) -> None:
+        """bikerack with no subcommand should invoke start."""
+        # Running without subcommand should behave like 'start'
+        # Since start is not implemented, it should error
+        result = subprocess.run(
+            [sys.executable, "-m", "pennyfarthing_scripts.bikerack"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            cwd=str(Path(__file__).parent.parent.parent),
+        )
+
+        # Should fail (NotImplementedError in start) but not with usage error
+        assert result.returncode != 0
+
+
+# ---------------------------------------------------------------------------
+# Utility function tests
+# ---------------------------------------------------------------------------
+
+
+class TestProcessAlive:
+    """Utility: is_process_alive checks if PID is running."""
+
+    def test_detects_own_process(self) -> None:
+        """is_process_alive should return True for current process."""
+        result = is_process_alive(os.getpid())
+        assert result is True
+
+    def test_returns_false_for_invalid_pid(self) -> None:
+        """is_process_alive should return False for non-existent PID."""
+        result = is_process_alive(999999999)
+        assert result is False
+
+
+class TestCleanupFiles:
+    """Utility: cleanup_files removes port and PID files."""
+
+    def test_removes_port_file(self, tmp_path: Path) -> None:
+        """cleanup_files should remove .bikerack-port."""
+        port_file = tmp_path / ".bikerack-port"
+        port_file.write_text("2898")
+
+        cleanup_files(tmp_path)
+
+        assert not port_file.exists()
+
+    def test_removes_pid_file(self, tmp_path: Path) -> None:
+        """cleanup_files should remove .bikerack-pid."""
+        pid_file = tmp_path / ".bikerack-pid"
+        pid_file.write_text("12345")
+
+        cleanup_files(tmp_path)
+
+        assert not pid_file.exists()
+
+    def test_no_error_when_files_missing(self, tmp_path: Path) -> None:
+        """cleanup_files should not error when files don't exist."""
+        # Should not raise
+        cleanup_files(tmp_path)
+
+
+class TestReadPortFile:
+    """Utility: read_port_file reads port from file."""
+
+    def test_reads_port(self, tmp_path: Path) -> None:
+        """read_port_file should return port as integer."""
+        (tmp_path / ".bikerack-port").write_text("2898")
+
+        result = read_port_file(tmp_path)
+
+        assert result == 2898
+
+    def test_returns_none_when_missing(self, tmp_path: Path) -> None:
+        """read_port_file should return None when file doesn't exist."""
+        result = read_port_file(tmp_path)
+
+        assert result is None
+
+    def test_handles_trailing_whitespace(self, tmp_path: Path) -> None:
+        """read_port_file should handle trailing newlines/spaces."""
+        (tmp_path / ".bikerack-port").write_text("2898\n")
+
+        result = read_port_file(tmp_path)
+
+        assert result == 2898