"""Cross-platform path helpers using pathlib.

All path construction goes through this module to ensure
consistent behavior on macOS, Linux, and Windows.
"""

from pathlib import Path


def ensure_dir(path: Path) -> Path:
    """Create directory (and parents) if it doesn't exist. Returns the path."""
    path.mkdir(parents=True, exist_ok=True)
    return path


def assessment_dirs(working_dir: Path) -> dict[str, Path]:
    """Return the standard assessment directory structure.

    These are the directories the MCP server creates manually.
    The SFDX project structure under {customer}/ is created by sf CLI.
    """
    return {
        "working_dir": working_dir,
        "package_repos": working_dir / "package-repos",
        "from_version": working_dir / "package-repos" / "from-version",
        "to_version": working_dir / "package-repos" / "to-version",
        "analysis": working_dir / "analysis",
        "per_package": working_dir / "analysis" / "per-package",
    }


def project_dirs(working_dir: Path, customer: str) -> dict[str, Path]:
    """Return paths within the SFDX project (created by sf CLI)."""
    project = working_dir / customer
    return {
        "project_root": project,
        "manifest": project / "manifest",
        "force_app": project / "force-app" / "main" / "default",
        "settings_export": project / "cs-settings-export",
    }


def cache_dir() -> Path:
    """Return the cross-customer cache directory for package diff results."""
    return Path.home() / ".cloudsense-upgrade-cache"
