fix: clean error message (no traceback) and correct db path on schema mismatch (#1029)

* fix: show clean error (no traceback) and correct db path on schema mismatch [AI-assisted]

- Catch SchemaVersionError at import time in cli.py; display via status_logger
  so the user sees a clean message instead of a raw Python traceback
- Replace <db_path> placeholder with the actual database path in error messages

* style: fix ruff import ordering in cli.py [AI-assisted]

---------

Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>

Author: coding-ai-assistant[bot]

src/aletheia_probe/cache/schema.py

@@ -104,7 +104,7 @@ def check_schema_compatibility(db_path: Path) -> bool:
             f"Database schema is from an old version of aletheia-probe (pre-1.0) "
             f"and cannot be used with this version (requires schema {SCHEMA_VERSION}).\n\n"
             f"Please delete the database and run sync again:\n"
-            f"  rm <db_path>\n"
+            f"  rm {db_path}\n"
             f"  aletheia-probe sync"
         )
 
@@ -113,7 +113,7 @@ def check_schema_compatibility(db_path: Path) -> bool:
             f"Database schema version ({current_version}) is too old "
             f"(requires {SCHEMA_VERSION}).\n\n"
             f"Please delete the database and run sync again:\n"
-            f"  rm <db_path>\n"
+            f"  rm {db_path}\n"
             f"  aletheia-probe sync"
         )
 

src/aletheia_probe/cli.py

@@ -15,7 +15,7 @@
 from . import __version__
 from .batch_assessor import BibtexBatchAssessor
 from .cache import AcronymCache, AssessmentCache, RetractionCache
-from .cache_sync import cache_sync_manager
+from .cache.schema import SchemaVersionError
 from .config import get_config_manager
 from .dispatcher import query_dispatcher
 from .enums import AssessmentType
@@ -25,6 +25,16 @@
 from .utils.dead_code import code_is_used
 
 
+# Import cache_sync last: instantiation at module level may raise SchemaVersionError
+# if the database schema is outdated. Caught here for a clean error message.
+_startup_error: SchemaVersionError | None = None
+try:
+    from .cache_sync import cache_sync_manager  # noqa: E402
+except SchemaVersionError as _e:
+    _startup_error = _e
+    cache_sync_manager = None  # type: ignore[assignment]
+
+
 F = TypeVar("F", bound=Callable[..., Any])
 
 
@@ -148,6 +158,11 @@ def main(ctx: click.Context, config: Path | None) -> None:
     detail_logger, status_logger = setup_logging()
     detail_logger.debug("CLI initialized")
 
+    # Fail cleanly if the database schema was incompatible at startup
+    if _startup_error is not None:
+        status_logger.error(str(_startup_error))
+        sys.exit(1)
+
     # Initialize config manager with custom path if provided
     if config:
         detail_logger.debug(f"Using config file: {config}")