"""Helpers for opening local folders from the GUI."""

from __future__ import annotations

import os
import subprocess
import sys


def open_in_file_manager(path: str) -> str:
    """Open an existing directory with the platform file manager.

    Returns the absolute path that was opened. The helper never creates
    directories; callers should present FileNotFoundError as a user-facing
    warning.
    """

    target = os.path.abspath(str(path or ""))
    if not os.path.isdir(target):
        raise FileNotFoundError(f"目录不存在：{target}")

    if sys.platform.startswith("win"):
        startfile = getattr(os, "startfile", None)
        if startfile is None:
            raise OSError("当前系统不支持打开文件夹")
        startfile(target)
        return target

    command = ["open", target] if sys.platform == "darwin" else ["xdg-open", target]
    subprocess.Popen(
        command,
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        shell=False,
    )
    return target