trcc-linux 8.3.2__tar.gz → 8.3.4__tar.gz

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 8.3.2
+Version: 8.3.4
 Summary: Linux implementation of Thermalright LCD Control Center
 Project-URL: Homepage, https://github.com/Lexonight1/thermalright-trcc-linux
 Project-URL: Documentation, https://github.com/Lexonight1/thermalright-trcc-linux#readme
@@ -74,8 +74,8 @@ Description-Content-Type: text/markdown
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4784_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-73%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4795_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-74%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
 [![Type Check](https://img.shields.io/badge/type_check-pyright-blue?logo=python&logoColor=white)](https://microsoft.github.io/pyright/)
@@ -186,13 +186,13 @@ Pre-built packages are available for every major distro. No pip, no venv, no PEP
 
 **Fedora / openSUSE / Nobara:**
 ```bash
-sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1.fc43.noarch.rpm
+sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.4-1.fc43.noarch.rpm
 ```
 
 **Ubuntu 24.04+ / Debian 13+ / Mint 22+ / Pop!_OS 24.04+ / Zorin 17+:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.1-1_all.deb
-sudo dpkg -i trcc-linux_8.3.1-1_all.deb
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.4-1_all.deb
+sudo dpkg -i trcc-linux_8.3.4-1_all.deb
 sudo apt-get install -f    # pulls in any missing dependencies
 ```
 
@@ -200,8 +200,8 @@ sudo apt-get install -f    # pulls in any missing dependencies
 
 **Arch / CachyOS / Manjaro / EndeavourOS / Garuda:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1-any.pkg.tar.zst
-sudo pacman -U trcc-linux-8.3.1-1-any.pkg.tar.zst
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.4-1-any.pkg.tar.zst
+sudo pacman -U trcc-linux-8.3.4-1-any.pkg.tar.zst
 ```
 
 **NixOS** — add to your `flake.nix` inputs:

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/README.md

@@ -10,8 +10,8 @@
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4784_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-73%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4795_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-74%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
 [![Type Check](https://img.shields.io/badge/type_check-pyright-blue?logo=python&logoColor=white)](https://microsoft.github.io/pyright/)
@@ -122,13 +122,13 @@ Pre-built packages are available for every major distro. No pip, no venv, no PEP
 
 **Fedora / openSUSE / Nobara:**
 ```bash
-sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1.fc43.noarch.rpm
+sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.4-1.fc43.noarch.rpm
 ```
 
 **Ubuntu 24.04+ / Debian 13+ / Mint 22+ / Pop!_OS 24.04+ / Zorin 17+:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.1-1_all.deb
-sudo dpkg -i trcc-linux_8.3.1-1_all.deb
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.4-1_all.deb
+sudo dpkg -i trcc-linux_8.3.4-1_all.deb
 sudo apt-get install -f    # pulls in any missing dependencies
 ```
 
@@ -136,8 +136,8 @@ sudo apt-get install -f    # pulls in any missing dependencies
 
 **Arch / CachyOS / Manjaro / EndeavourOS / Garuda:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1-any.pkg.tar.zst
-sudo pacman -U trcc-linux-8.3.1-1-any.pkg.tar.zst
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.4-1-any.pkg.tar.zst
+sudo pacman -U trcc-linux-8.3.4-1-any.pkg.tar.zst
 ```
 
 **NixOS** — add to your `flake.nix` inputs:

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trcc-linux"
-version = "8.3.2"
+version = "8.3.4"
 description = "Linux implementation of Thermalright LCD Control Center"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/__version__.py

@@ -1,4 +1,4 @@
 """TRCC Linux version information. History in doc/CHANGELOG.md."""
 
-__version__ = "8.3.2"
+__version__ = "8.3.4"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/api/__init__.py

@@ -250,9 +250,10 @@ def mount_static_dirs(width: int, height: int) -> None:
              width, height, theme_dir, web_dir, masks_dir)
 
 
-# ── Token auth middleware (optional, enabled via --token) ─────────────
+# ── Token auth + pairing ──────────────────────────────────────────────
 
 _api_token: str | None = None
+_pairing_code: str | None = None  # Ephemeral 6-char code, shown in terminal
 
 
 def configure_auth(token: str | None) -> None:
@@ -261,10 +262,20 @@ def configure_auth(token: str | None) -> None:
     _api_token = token
 
 
+def set_pairing_code(code: str) -> None:
+    """Set the ephemeral pairing code (displayed in terminal)."""
+    global _pairing_code  # noqa: PLW0603
+    _pairing_code = code
+
+
+# Paths exempt from token auth — pairing needs to work before the phone has a token
+_AUTH_EXEMPT = {"/health", "/pair"}
+
+
 @app.middleware("http")
 async def check_token(request: Request, call_next):
     """Reject requests without valid token (if token is configured)."""
-    if _api_token and request.url.path != "/health":
+    if _api_token and request.url.path not in _AUTH_EXEMPT:
         header_token = request.headers.get("X-API-Token", "")
         if not hmac.compare_digest(header_token, _api_token):
             return JSONResponse(status_code=401, content={"detail": "Invalid token"})
@@ -279,6 +290,37 @@ def health() -> dict:
     return {"status": "ok", "version": __version__}
 
 
+# ── Pairing endpoint (no auth required) ───────────────────────────────
+
+@app.post("/pair")
+def pair_device(code: str):
+    """Pair a remote device using the 6-char code shown in the terminal.
+
+    Returns the persistent API token on success. The remote app stores
+    this token and uses it for all future requests (X-API-Token header).
+    No re-pairing needed after server restart.
+    """
+    if not _pairing_code:
+        return JSONResponse(
+            status_code=503,
+            content={"detail": "Pairing not available (server started with --token)"},
+        )
+
+    if not hmac.compare_digest(code.upper(), _pairing_code.upper()):
+        log.warning("Pairing attempt with wrong code")
+        return JSONResponse(
+            status_code=403, content={"detail": "Invalid pairing code"},
+        )
+
+    if not _api_token:
+        return JSONResponse(
+            status_code=500, content={"detail": "No API token configured"},
+        )
+
+    log.info("Remote device paired successfully")
+    return {"success": True, "token": _api_token}
+
+
 # ── Register routers ──────────────────────────────────────────────────
 
 from trcc.api.devices import router as devices_router  # noqa: E402

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/api/devices.py

@@ -121,6 +121,11 @@ def select_device(device_id: int) -> dict:
             api._display_dispatcher = lcd
 
             w_res, h_res = dev.resolution or (320, 320)
+
+            # Download/extract theme data for this resolution (no-op if cached)
+            from trcc.adapters.infra.data_repository import DataManager
+            DataManager.ensure_all(w_res, h_res)
+
             api.set_current_image(ImageService.solid_color(0, 0, 0, w_res, h_res))
 
             lcd.restore_device_settings()

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/api/themes.py

@@ -44,6 +44,25 @@ def _preview_url(theme_name: str, theme_dir: str) -> str:
     return ""
 
 
+@router.post("/init")
+def init_theme_data(resolution: str = "320x320") -> dict:
+    """Download and extract theme/web/mask archives for a resolution.
+
+    Safe to call repeatedly — no-op if data is already cached.
+    Designed for remote apps to call on startup before listing themes.
+    """
+    w, h = _parse_resolution(resolution)
+
+    from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_all(w, h)
+
+    # Remount static dirs now that data exists on disk
+    from trcc.api import mount_static_dirs
+    mount_static_dirs(w, h)
+
+    return {"success": True, "resolution": f"{w}x{h}"}
+
+
 @router.get("")
 def list_themes(resolution: str = "320x320") -> list[ThemeResponse]:
     """List available local themes for a given resolution."""
@@ -51,7 +70,8 @@ def list_themes(resolution: str = "320x320") -> list[ThemeResponse]:
 
     from pathlib import Path
 
-    from trcc.adapters.infra.data_repository import ThemeDir
+    from trcc.adapters.infra.data_repository import DataManager, ThemeDir
+    DataManager.ensure_themes(w, h)
     td = ThemeDir.for_resolution(w, h)
     theme_dir = Path(str(td))
     themes = ThemeService.discover_local(theme_dir, (w, h))
@@ -73,6 +93,7 @@ def list_web_themes(resolution: str = "320x320") -> list[WebThemeResponse]:
     w, h = _parse_resolution(resolution)
 
     from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_web(w, h)
     web_dir = DataManager.get_web_dir(w, h)
 
     results: list[WebThemeResponse] = []
@@ -163,6 +184,7 @@ def list_masks(resolution: str = "320x320") -> list[MaskResponse]:
     w, h = _parse_resolution(resolution)
 
     from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_web_masks(w, h)
     masks_dir = DataManager.get_web_masks_dir(w, h)
 
     results: list[MaskResponse] = []

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/cli/__init__.py

@@ -836,9 +836,27 @@ def _cmd_serve(
     )] = None,
 ) -> int:
     """Start REST API server."""
-    import uvicorn  # noqa: I001
+    import secrets  # noqa: I001
+    import string
+
+    import uvicorn
+
+    from trcc.api import app as api_app, configure_auth, set_pairing_code  # noqa: I001
+    from trcc.conf import Settings
+
+    # Token resolution: explicit --token > persistent config > auto-generate
+    pairing_code: Optional[str] = None
+    if token is not None:
+        # Explicit --token: save it, no pairing code needed
+        Settings.save_api_token(token)
+    else:
+        # Use persistent token (generated on first run, reused forever)
+        token = Settings.get_api_token()
+        # Generate ephemeral 6-char pairing code for phone to enter
+        alphabet = string.ascii_uppercase + string.digits
+        pairing_code = ''.join(secrets.choice(alphabet) for _ in range(6))
+        set_pairing_code(pairing_code)
 
-    from trcc.api import app as api_app, configure_auth
     configure_auth(token)
 
     ssl_kwargs: dict = {}
@@ -851,12 +869,18 @@ def _cmd_serve(
         ssl_kwargs = {"ssl_certfile": certs[0], "ssl_keyfile": certs[1]}
 
     # Warn if token travels in plaintext over LAN
-    if token and host != "127.0.0.1" and not ssl_kwargs:
-        print("WARNING: --token without --tls exposes your API key in plaintext on the network.")
+    if host != "127.0.0.1" and not ssl_kwargs:
+        print("WARNING: No --tls — traffic is unencrypted on the network.")
         print("         Add --tls for HTTPS, or use --cert/--key for a custom certificate.")
 
     scheme = "https" if ssl_kwargs else "http"
     print(f"Serving on {scheme}://{host}:{port}")
+
+    if pairing_code:
+        print(f"\n  Pairing code:  {pairing_code}\n")
+        print("  Enter this code in TRCC Remote to pair your phone.")
+        print("  After pairing, the phone stays connected across restarts.\n")
+
     _print_serve_qr(host, port, token, bool(ssl_kwargs))
     uvicorn.run(api_app, host=host, port=port, **ssl_kwargs)
     return 0

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/src/trcc/conf.py

@@ -366,6 +366,32 @@ class Settings:
         config.pop("installed_resolutions", None)
         save_config(config)
 
+    @staticmethod
+    def get_api_token() -> str:
+        """Get persistent API token, generating one on first call.
+
+        Stored in config.json so it survives restarts — phone pairs once,
+        stays trusted forever.
+        """
+        import secrets
+        import string
+
+        config = load_config()
+        token = config.get('api_token')
+        if not token:
+            alphabet = string.ascii_letters + string.digits
+            token = ''.join(secrets.choice(alphabet) for _ in range(16))
+            config['api_token'] = token
+            save_config(config)
+        return token
+
+    @staticmethod
+    def save_api_token(token: str) -> None:
+        """Save an explicit API token (from --token flag)."""
+        config = load_config()
+        config['api_token'] = token
+        save_config(config)
+
     # --- Instance methods and properties ---
 
     def __init__(self) -> None:

{trcc_linux-8.3.2 → trcc_linux-8.3.4}/tests/api/test_api.py

@@ -1102,6 +1102,212 @@ class TestIPCFrameSharing(unittest.TestCase):
         self.assertTrue(resp.content[:4] == b'\x89PNG')
 
 
+# =============================================================================
+# Standalone mode — theme data init + auto-token
+# =============================================================================
+
+class TestStandaloneThemeInit(unittest.TestCase):
+    """API endpoints trigger theme data download in standalone mode."""
+
+    def setUp(self):
+        configure_auth(None)
+        self.client = TestClient(app)
+
+    def tearDown(self):
+        api_module._display_dispatcher = None
+        api_module._current_image = None
+
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_all')
+    def test_init_theme_data_calls_ensure_all(self, mock_ensure):
+        """POST /themes/init triggers DataManager.ensure_all() for the resolution."""
+        resp = self.client.post("/themes/init?resolution=320x320")
+        self.assertEqual(resp.status_code, 200)
+        self.assertTrue(resp.json()["success"])
+        mock_ensure.assert_called_once_with(320, 320)
+
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_all')
+    def test_init_theme_data_invalid_resolution(self, mock_ensure):
+        """POST /themes/init rejects bad resolution."""
+        resp = self.client.post("/themes/init?resolution=bad")
+        self.assertEqual(resp.status_code, 400)
+        mock_ensure.assert_not_called()
+
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_themes')
+    @patch('trcc.api.themes.ThemeService.discover_local', return_value=[])
+    @patch('trcc.adapters.infra.data_repository.ThemeDir.for_resolution',
+           return_value=MagicMock(__str__=lambda s: '/tmp/themes', path='/tmp/themes'))
+    def test_list_themes_calls_ensure_themes(self, _td, _discover, mock_ensure):
+        """GET /themes triggers DataManager.ensure_themes() for the resolution."""
+        self.client.get("/themes?resolution=320x320")
+        mock_ensure.assert_called_once_with(320, 320)
+
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_web')
+    @patch('trcc.adapters.infra.data_repository.DataManager.get_web_dir', return_value='/nonexistent')
+    def test_list_web_themes_calls_ensure_web(self, _dir, mock_ensure):
+        """GET /themes/web triggers DataManager.ensure_web() for the resolution."""
+        self.client.get("/themes/web?resolution=480x480")
+        mock_ensure.assert_called_once_with(480, 480)
+
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_web_masks')
+    @patch('trcc.adapters.infra.data_repository.DataManager.get_web_masks_dir', return_value='/nonexistent')
+    def test_list_masks_calls_ensure_web_masks(self, _dir, mock_ensure):
+        """GET /themes/masks triggers DataManager.ensure_web_masks() for the resolution."""
+        self.client.get("/themes/masks?resolution=320x320")
+        mock_ensure.assert_called_once_with(320, 320)
+
+    @patch('trcc.ipc.IPCClient')
+    @patch('trcc.cli._device.discover_resolution')
+    @patch('trcc.adapters.infra.data_repository.DataManager.ensure_all')
+    def test_select_device_standalone_calls_ensure_all(
+        self, mock_ensure_all, mock_discover, mock_ipc,
+    ):
+        """select_device() standalone path calls DataManager.ensure_all()."""
+        mock_ipc.available.return_value = False
+
+        dev = DeviceInfo(name="LCD1", path="/dev/sg0", vid=0x0402, pid=0x3922,
+                         protocol="scsi", resolution=(320, 320))
+        _device_svc._devices = [dev]
+
+        resp = self.client.post("/devices/0/select")
+        self.assertEqual(resp.status_code, 200)
+        mock_ensure_all.assert_called_once_with(320, 320)
+        api_module._display_dispatcher = None
+
+
+class TestPairing(unittest.TestCase):
+    """POST /pair — device pairing flow."""
+
+    def setUp(self):
+        configure_auth("persistent-token-abc")
+        api_module.set_pairing_code("A3X7K2")
+        self.client = TestClient(app)
+
+    def tearDown(self):
+        configure_auth(None)
+        api_module.set_pairing_code(None)
+
+    def test_pair_correct_code_returns_token(self):
+        """Correct pairing code returns the persistent API token."""
+        resp = self.client.post("/pair?code=A3X7K2")
+        self.assertEqual(resp.status_code, 200)
+        data = resp.json()
+        self.assertTrue(data["success"])
+        self.assertEqual(data["token"], "persistent-token-abc")
+
+    def test_pair_case_insensitive(self):
+        """Pairing code is case-insensitive."""
+        resp = self.client.post("/pair?code=a3x7k2")
+        self.assertEqual(resp.status_code, 200)
+        self.assertTrue(resp.json()["success"])
+
+    def test_pair_wrong_code_rejected(self):
+        """Wrong pairing code returns 403."""
+        resp = self.client.post("/pair?code=WRONG1")
+        self.assertEqual(resp.status_code, 403)
+
+    def test_pair_no_pairing_code_set(self):
+        """Returns 503 when server started with --token (no pairing)."""
+        api_module.set_pairing_code(None)
+        resp = self.client.post("/pair?code=A3X7K2")
+        self.assertEqual(resp.status_code, 503)
+
+    def test_pair_bypasses_auth(self):
+        """POST /pair works without X-API-Token header."""
+        # Auth is configured, but /pair should be exempt
+        resp = self.client.post("/pair?code=A3X7K2")
+        self.assertEqual(resp.status_code, 200)
+
+
+class TestPersistentToken:
+    """Persistent API token in config.json."""
+
+    def test_get_api_token_generates_on_first_call(self):
+        """First call generates a 16-char token and persists it."""
+        import string
+
+        from trcc.conf import Settings
+        token = Settings.get_api_token()
+        assert len(token) == 16
+        valid = set(string.ascii_letters + string.digits)
+        assert all(c in valid for c in token)
+
+    def test_get_api_token_returns_same_on_second_call(self):
+        """Second call returns the same persisted token."""
+        from trcc.conf import Settings
+        t1 = Settings.get_api_token()
+        t2 = Settings.get_api_token()
+        assert t1 == t2
+
+    def test_save_api_token_overrides(self):
+        """Explicit --token overrides the persisted token."""
+        from trcc.conf import Settings
+        Settings.save_api_token("explicit-override")
+        assert Settings.get_api_token() == "explicit-override"
+
+    def test_serve_uses_persistent_token(self):
+        """trcc serve with no --token uses persistent config token."""
+        from trcc.cli import _cmd_serve
+
+        captured_token = None
+
+        def capture_auth(token):
+            nonlocal captured_token
+            captured_token = token
+
+        with patch('trcc.api.configure_auth', side_effect=capture_auth):
+            with patch('trcc.api.set_pairing_code'):
+                with patch('uvicorn.run'):
+                    with patch('trcc.cli._print_serve_qr'):
+                        _cmd_serve(token=None)
+
+        assert captured_token is not None
+        assert len(captured_token) == 16
+
+    def test_serve_explicit_token_saves_to_config(self):
+        """trcc serve --token saves the explicit token to config."""
+        from trcc.cli import _cmd_serve
+        from trcc.conf import Settings
+
+        with patch('trcc.api.configure_auth'):
+            with patch('trcc.api.set_pairing_code'):
+                with patch('uvicorn.run'):
+                    with patch('trcc.cli._print_serve_qr'):
+                        _cmd_serve(token="myCustom99")
+
+        assert Settings.get_api_token() == "myCustom99"
+
+    def test_serve_generates_pairing_code_when_no_explicit_token(self):
+        """trcc serve without --token generates a 6-char pairing code."""
+        from trcc.cli import _cmd_serve
+
+        captured_code = None
+
+        def capture_code(code):
+            nonlocal captured_code
+            captured_code = code
+
+        with patch('trcc.api.configure_auth'):
+            with patch('trcc.api.set_pairing_code', side_effect=capture_code):
+                with patch('uvicorn.run'):
+                    with patch('trcc.cli._print_serve_qr'):
+                        _cmd_serve(token=None)
+
+        assert captured_code is not None
+        assert len(captured_code) == 6
+
+    def test_serve_no_pairing_code_with_explicit_token(self):
+        """trcc serve --token skips pairing code generation."""
+        from trcc.cli import _cmd_serve
+
+        with patch('trcc.api.configure_auth'):
+            with patch('trcc.api.set_pairing_code') as mock_code:
+                with patch('uvicorn.run'):
+                    with patch('trcc.cli._print_serve_qr'):
+                        _cmd_serve(token="explicit")
+
+        mock_code.assert_not_called()
+
+
 # =============================================================================
 # dispatch_result — shared API helper
 # =============================================================================