feat(project): add project root discovery utilities

This PR centralizes project root discovery by introducing a dedicated utility module with multiple fallback strategies, replacing ad-hoc path calculations throughout the codebase. The changes improve reliability and maintainability by providing a consistent way to locate the project root directory.

* Added get_project_root() utility function with caching and multiple discovery strategies
* Refactored environment variable loading to use centralized project root discovery
* Introduced custom ProjectRootError exception for clearer error handling

Author: betmoar

src/tracklistify/cli.py

@@ -13,6 +13,7 @@
 
 # Local/package imports
 from .utils.logger import get_logger, set_logger
+from .utils.project import get_project_root
 
 # Get the logger for this module
 logger = get_logger(__name__)
@@ -145,8 +146,8 @@ def cli() -> None:
     logger.info("Starting CLI")
 
     # Load environment variables first
-    env_path = Path(__file__).parent.parent / ".env"
-    load_environment_variables(env_path)
+    env_file = get_project_root() / ".env"
+    load_environment_variables(env_file)
 
     try:
         exit_code = asyncio.run(main(args))

src/tracklistify/core/run.py

@@ -1,25 +1,21 @@
-#!/usr/bin/env python3
+"""Main entry point for Tracklistify."""
 
 import asyncio
 import signal
 import sys
-from pathlib import Path
+
+from tracklistify.utils.project import get_project_root
 
 # Global variables for cleanup
 _cleanup_tasks = set()
 
 
 def setup_environment():
     """Setup the Python path and environment variables."""
-    # Add the parent directory to Python path so tracklistify can be imported
-    current_dir = Path(__file__).parent.absolute()
-    sys.path.append(str(current_dir))
-
-    # Load environment variables from .env file if it exists
-    env_file = current_dir / ".env"
-    if not env_file.exists() and (current_dir / ".env.example").exists():
+    env_file = get_project_root() / ".env"
+    if not env_file.exists() and (get_project_root() / ".env.example").exists():
         print("Creating .env from .env.example...")
-        with open(current_dir / ".env.example") as f:
+        with open(get_project_root() / ".env.example") as f:
             with open(env_file, "w") as env:
                 env.write(f.read())
         print("Please edit .env with your credentials")

src/tracklistify/utils/project.py

@@ -0,0 +1,71 @@
+"""Project root discovery utilities."""
+
+import os
+from functools import lru_cache
+from importlib.metadata import PackageNotFoundError, distribution
+from pathlib import Path
+
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ProjectRootError(Exception):
+    """Raised when project root cannot be determined."""
+
+@lru_cache(maxsize=1)
+def get_project_root() -> Path:
+    """Get project root directory with multiple fallback strategies.
+
+    The result is cached for performance as project root doesn't change during runtime.
+
+    Returns:
+        Path: Absolute path to the project root directory
+
+    Raises:
+        ProjectRootError: If project root cannot be determined reliably
+    """
+
+    project_root_env = os.getenv("TRACKLISTIFY_PROJECT_ROOT")
+
+    if project_root_env:
+        try:
+            project_root = Path(project_root_env).resolve()
+            if project_root.exists():
+                return project_root
+        except (OSError, ValueError):
+            pass
+
+    current_file = Path(__file__).resolve()
+
+    for parent in [current_file] + list(current_file.parents):
+        pyproject_path = parent / "pyproject.toml"
+        if pyproject_path.exists():
+            return parent
+
+    try:
+        dist = distribution("tracklistify")
+        package_path = Path(dist.locate_file(""))
+
+        if (package_path / "pyproject.toml").exists():
+            return package_path
+
+        for parent in package_path.parents:
+            pyproject_path = parent / "pyproject.toml"
+            if pyproject_path.exists():
+                return parent
+
+    except (PackageNotFoundError, AttributeError, OSError):
+        pass
+
+    raise ProjectRootError(
+        "Unable to determine project root. Please set TRACKLISTIFY_PROJECT_ROOT "
+        "environment variable or ensure pyproject.toml exists in the project root."
+    )
+
+
+def clear_project_root_cache() -> None:
+    """Clear the cached project root."""
+
+    get_project_root.cache_clear()
+    logger.debug("Cleared project root cache")