"""File selector — GUI dialog or CLI fallback.

Provides a single function ``select_file`` that:
  1. Opens a tkinter file-dialog when a display is available.
  2. Falls back to ``sys.argv[1]`` in headless environments.
"""

import sys
from typing import Optional


def select_file() -> Optional[str]:
    """Open a file-selection dialog and return the chosen path, or None.

    Returns
    -------
    str | None
        Selected file path, or ``None`` if the user cancelled / no
        fallback is available.
    """
    # Try tkinter GUI dialog first
    try:
        import tkinter
        import tkinter.filedialog

        root = tkinter.Tk()
        root.withdraw()  # hide the main window
        root.attributes("-topmost", True)

        filepath = tkinter.filedialog.askopenfilename(
            title="选择 PinMAP 文件",
            filetypes=[
                ("Excel 文件", "*.xls *.xlsx"),
                ("所有文件", "*.*"),
            ],
        )
        root.destroy()

        if filepath:
            # tkinter may return a Tcl object; normalise to str
            return str(filepath)
        return None

    except (ImportError, Exception):
        # No display / no tkinter — fall back to CLI argument
        if len(sys.argv) > 1:
            return sys.argv[1]
        print("[WARN] 无 GUI 环境且未提供命令行参数")
        return None