style: add future annotations

src/lrx_cli/__main__.py

@@ -4,6 +4,8 @@ Date: 2026-04-06 08:19:54
 Description: The entry point.
 """
 
+from __future__ import annotations
+
 from .cli import run
 
 if __name__ == "__main__":

src/lrx_cli/authenticators/__init__.py

@@ -4,6 +4,8 @@ Date: 2026-04-06 08:21:01
 Description: Credential authenticators for third-party provider APIs
 """
 
+from __future__ import annotations
+
 from lrx_cli.authenticators.qqmusic import QQMusicAuthenticator
 
 from .base import BaseAuthenticator

src/lrx_cli/authenticators/base.py

@@ -4,6 +4,8 @@ Date: 2026-04-05 03:18:14
 Description: Base class for credential authenticators.
 """
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import Optional
 

src/lrx_cli/authenticators/dummy.py

@@ -4,6 +4,8 @@ Date: 2026-04-05 03:36:44
 Description: A dummy authenticator that does nothing and always reports as configured.
 """
 
+from __future__ import annotations
+
 from .base import BaseAuthenticator
 
 

src/lrx_cli/authenticators/musixmatch.py

@@ -4,6 +4,8 @@ Date: 2026-04-05 03:27:56
 Description: Musixmatch authenticator — token management, 401 retry, and cooldown.
 """
 
+from __future__ import annotations
+
 import time
 from typing import Optional
 from urllib.parse import urlencode

src/lrx_cli/authenticators/qqmusic.py

@@ -4,6 +4,8 @@ Date: 2026-04-05 03:47:30
 Description: QQ Music API authenticator - currently only a proxy.
 """
 
+from __future__ import annotations
+
 from typing import Optional
 import httpx
 from loguru import logger

src/lrx_cli/authenticators/spotify.py

@@ -4,6 +4,8 @@ Date: 2026-04-05 03:18:14
 Description: Spotify authenticator — TOTP-based access token via SP_DC cookie.
 """
 
+from __future__ import annotations
+
 import hashlib
 import hmac
 import struct

src/lrx_cli/cache.py

@@ -5,6 +5,8 @@ Description: SQLite-based lyric cache with per-source slot rows, TTL expiration,
              and schema migrations (confidence versioning + slot migration).
 """
 
+from __future__ import annotations
+
 import json
 import sqlite3
 import hashlib

src/lrx_cli/cli.py

@@ -4,6 +4,8 @@ Date: 2026-03-26 02:04:39
 Description: CLI interface.
 """
 
+from __future__ import annotations
+
 import sys
 import time
 import os

src/lrx_cli/config.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 10:17:56
 Description: Global configuration constants, typed config dataclasses, and logger setup.
 """
 
+from __future__ import annotations
+
 import dataclasses
 import os
 import sys

src/lrx_cli/core.py

@@ -5,6 +5,8 @@ Description: Core orchestrator — coordinates fetchers with cache-aware fallbac
              Also handles enrichers & authenticators & …
 """
 
+from __future__ import annotations
+
 import asyncio
 from typing import Optional
 from loguru import logger

src/lrx_cli/enrichers/__init__.py

@@ -4,6 +4,8 @@ Date: 2026-03-31 06:09:11
 Description: Metadata enrichment pipeline
 """
 
+from __future__ import annotations
+
 from loguru import logger
 
 from .base import BaseEnricher

src/lrx_cli/enrichers/audio_tag.py

@@ -4,6 +4,8 @@ Date: 2026-03-31 06:11:27
 Description: Enricher that reads metadata from audio file tags.
 """
 
+from __future__ import annotations
+
 from typing import Optional
 from loguru import logger
 from mutagen._file import File, FileType

src/lrx_cli/enrichers/base.py

@@ -4,6 +4,8 @@ Date: 2026-03-31 06:08:16
 Description: Base class for metadata enrichers.
 """
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import Optional
 

src/lrx_cli/enrichers/file_name.py

@@ -4,6 +4,8 @@ Date: 2026-03-31 06:08:44
 Description: Enricher that parses metadata from the audio file path.
 """
 
+from __future__ import annotations
+
 import re
 from typing import Optional
 from loguru import logger

src/lrx_cli/enrichers/musixmatch.py

@@ -4,8 +4,9 @@ Date: 2026-04-05 02:13:49
 Description: Musixmatch metadata enricher (matcher.track.get by Spotify track ID).
 """
 
-from typing import Optional
+from __future__ import annotations
 
+from typing import Optional
 from loguru import logger
 
 from .base import BaseEnricher

src/lrx_cli/fetchers/__init__.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 02:33:26
 Description: Fetcher pipeline — registry and types.
 """
 
+from __future__ import annotations
+
 from typing import Literal, Optional
 from loguru import logger
 

src/lrx_cli/fetchers/base.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 02:33:26
 Description: Base fetcher class and common interfaces.
 """
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import Optional
 from dataclasses import dataclass

src/lrx_cli/fetchers/cache_search.py

@@ -8,10 +8,11 @@ Description: Cache-search fetcher — cross-album fuzzy lookup in the local cach
              albums or is played from different players.
 """
 
+from __future__ import annotations
+
 from typing import Optional
 from loguru import logger
 
-
 from .base import BaseFetcher, FetchResult
 from .selection import SearchCandidate, select_best
 from ..models import TrackMeta, LyricResult, CacheStatus

src/lrx_cli/fetchers/local.py

@@ -7,6 +7,8 @@ Description: Local fetcher — reads lyrics from .lrc sidecar files or embedded
                2. Embedded lyrics in audio metadata (FLAC, MP3 USLT/SYLT tags)
 """
 
+from __future__ import annotations
+
 from typing import Optional
 from loguru import logger
 from mutagen._file import File

src/lrx_cli/fetchers/lrclib.py

@@ -5,6 +5,8 @@ Description: LRCLIB fetcher — queries lrclib.net for synced/plain lyrics.
              Requires complete track metadata (artist, title, album, duration).
 """
 
+from __future__ import annotations
+
 import httpx
 from loguru import logger
 from urllib.parse import urlencode

src/lrx_cli/fetchers/lrclib_search.py

@@ -5,6 +5,8 @@ Description: LRCLIB search fetcher — fuzzy search via lrclib.net /api/search.
              Used when metadata is incomplete (no album or duration) but title is available.
 """
 
+from __future__ import annotations
+
 import asyncio
 import httpx
 from loguru import logger

src/lrx_cli/fetchers/musixmatch.py

@@ -11,6 +11,8 @@ Description: Musixmatch fetchers (desktop API, anonymous or usertoken auth).
              musixmatch          — metadata search + best-candidate fallback
 """
 
+from __future__ import annotations
+
 import json
 from typing import Optional
 from loguru import logger

src/lrx_cli/fetchers/netease.py

@@ -7,6 +7,8 @@ Description: Netease Cloud Music fetcher.
              retrieving lyrics. No authentication required.
 """
 
+from __future__ import annotations
+
 import asyncio
 import httpx
 from loguru import logger

src/lrx_cli/fetchers/qqmusic.py

@@ -9,6 +9,8 @@ Description: QQ Music fetcher via self-hosted API proxy.
              Search → pick best match → fetch LRC lyrics.
 """
 
+from __future__ import annotations
+
 import asyncio
 from loguru import logger
 

src/lrx_cli/fetchers/selection.py

@@ -8,6 +8,8 @@ Description: Shared candidate-selection logic for search-based fetchers.
              proximity, and sync status.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from typing import Generic, Optional, TypeVar
 

src/lrx_cli/fetchers/spotify.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 10:43:21
 Description: Spotify fetcher — obtains synced lyrics via Spotify's internal color-lyrics API.
 """
 
+from __future__ import annotations
+
 from loguru import logger
 
 from .base import BaseFetcher, FetchResult

src/lrx_cli/lrc.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 21:54:01
 Description: LRC parsing, modeling, and serialization helpers.
 """
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 import re

src/lrx_cli/mpris.py

@@ -4,6 +4,8 @@ Date: 2026-03-25 04:44:15
 Description: MPRIS integration for fetching track metadata.
 """
 
+from __future__ import annotations
+
 import asyncio
 from dbus_next.aio.message_bus import MessageBus
 from dbus_next.constants import BusType

src/lrx_cli/normalize.py

@@ -5,6 +5,8 @@ Description: Shared text normalization utilities for fuzzy matching.
              Used by cache key generation, cache search, and candidate selection scoring.
 """
 
+from __future__ import annotations
+
 import re
 import unicodedata
 

src/lrx_cli/watch/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from .session import WatchCoordinator
 
 __all__ = ["WatchCoordinator"]

src/lrx_cli/watch/control.py

@@ -4,6 +4,9 @@ Date: 2026-04-10 08:14:58
 Description: Unix-socket control channel for communicating with a running watch session.
 """
 
+from __future__ import annotations
+
+
 import asyncio
 import json
 from pathlib import Path

src/lrx_cli/watch/fetcher.py

@@ -4,6 +4,9 @@ Date: 2026-04-10 08:14:41
 Description: Debounced lyric fetch orchestration for watch session.
 """
 
+from __future__ import annotations
+
+
 import asyncio
 from typing import Awaitable, Callable, Optional
 

src/lrx_cli/watch/player.py

@@ -4,6 +4,9 @@ Date: 2026-04-10 08:14:27
 Description: Player discovery, state monitoring, and active-player selection for watch mode.
 """
 
+from __future__ import annotations
+
+
 from dataclasses import dataclass
 from typing import Callable, Optional
 import asyncio

src/lrx_cli/watch/session.py

@@ -8,6 +8,8 @@ Description: Watch orchestration with explicit MVVM role boundaries.
              - Coordinator: WatchCoordinator wires services and drives async workflows.
 """
 
+from __future__ import annotations
+
 import asyncio
 from dataclasses import asdict
 from typing import Optional

src/lrx_cli/watch/tracker.py

@@ -4,6 +4,9 @@ Date: 2026-04-10 08:13:35
 Description: Playback position tracking utilities for watch mode.
 """
 
+from __future__ import annotations
+
+
 import asyncio
 import time
 from typing import Awaitable, Callable, Optional

src/lrx_cli/watch/view/__init__.py

@@ -1,5 +1,7 @@
 """Output abstraction types for watch mode rendering."""
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from bisect import bisect_right
 from dataclasses import dataclass

src/lrx_cli/watch/view/pipe.py

@@ -4,6 +4,8 @@ Date: 2026-04-10 08:15:17
 Description: Pipe output implementation for watch mode.
 """
 
+from __future__ import annotations
+
 from bisect import bisect_right
 from dataclasses import dataclass
 import sys

src/lrx_cli/watch/view/print.py

@@ -4,6 +4,8 @@ Date: 2026-04-10 08:15:31
 Description: Print output implementation for watch mode — one shot per track.
 """
 
+from __future__ import annotations
+
 import sys
 
 from . import BaseOutput, WatchState, WatchStatus

tests/test_config.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 from lrx_cli.config import AppConfig, CredentialConfig, WatchConfig, load_config

tests/test_fetchers.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import replace
 import asyncio
 import json