Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

66.2 KB
Raw Blame
from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Any

import pytest

from marimo._plugins.ui._impl import file_browser as fb_module
from marimo._plugins.ui._impl.file_browser import (
    FileBrowserFileInfo,
    ListDirectoryArgs,
    ListDirectoryResponse,
    _is_path_within,
    _normalize_selection_mode,
    _normalize_values,
    file_browser,
)
from marimo._utils.paths import normalize_path


@pytest.mark.parametrize(
    ("value", "expected"),
    [
        (None, ()),
        ("file.txt", ("file.txt",)),
        (Path("file.txt"), (Path("file.txt"),)),
        (["first.txt", "second.txt"], ["first.txt", "second.txt"]),
        (("first.txt", "second.txt"), ("first.txt", "second.txt")),
    ],
)
def test_normalize_values(
    value: str | Path | list[str] | tuple[str, ...] | None,
    expected: list[str | Path] | tuple[str | Path, ...],
) -> None:
    assert _normalize_values(value, multiple=True) == expected


def test_normalize_values_rejects_multiple_values() -> None:
    with pytest.raises(ValueError, match="multiple=False"):
        _normalize_values(["first.txt", "second.txt"], multiple=False)


def test_normalize_values_rejects_empty_string() -> None:
    with pytest.raises(ValueError, match='Invalid value=""'):
        _normalize_values("", multiple=True)


def test_normalize_values_rejects_empty_string_in_sequence() -> None:
    with pytest.raises(ValueError, match=r'Invalid value\[1\]=""'):
        _normalize_values(["first.txt", ""], multiple=True)


def test_normalize_values_reports_index_for_single_element_sequence() -> None:
    with pytest.raises(ValueError, match=r'Invalid value\[0\]=""'):
        _normalize_values([""], multiple=True)


def test_is_path_within_cases(tmp_path: Path) -> None:
    root = tmp_path.resolve()
    jail = root / "jail"
    jail.mkdir()
    inside = jail / "in.txt"
    inside.write_text("x")
    sub = jail / "sub"
    sub.mkdir()
    outside = root / "out.txt"
    outside.write_text("y")

    assert _is_path_within(inside, jail) is True
    assert _is_path_within(sub, jail) is True
    assert _is_path_within(jail, jail) is True
    assert _is_path_within(outside, jail) is False
    assert _is_path_within(root, jail) is False
    # Containment does not require existence.
    assert _is_path_within(jail / "nope.txt", jail) is True
    assert _is_path_within(root / "nope.txt", jail) is False


def test_is_path_within_rejects_symlink_escape(tmp_path: Path) -> None:
    root = tmp_path.resolve()
    jail = root / "jail"
    jail.mkdir()
    outside = root / "secret.txt"
    outside.write_text("s")
    escape = jail / "escape.txt"
    try:
        escape.symlink_to(outside)
    except OSError:
        pytest.skip("Cannot create symlinks on this system")

    assert _is_path_within(escape, jail) is False


def test_default_navigation_restriction_confines_list_directory(
    tmp_path: Path,
) -> None:
    fb = file_browser(initial_path=tmp_path)
    (tmp_path / "inside").mkdir()

    resp = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
    assert any(f["name"] == "inside" for f in resp.files)

    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(tmp_path.parent)))


def test_default_navigation_restriction_confines_cloud_path(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    cloudpathlib = pytest.importorskip("cloudpathlib")
    client = cloudpathlib.S3Client(
        aws_access_key_id="test",
        aws_secret_access_key="test",
        local_cache_dir=tmp_path,
    )
    root = cloudpathlib.S3Path("s3://bucket/root", client=client)
    nested = root / "nested"
    selected = root / "selected.txt"

    monkeypatch.setattr(
        client,
        "_is_file_or_dir",
        lambda path: "file" if path == selected else "dir",
    )

    def list_dir(path: Any, recursive: bool = False) -> Any:
        assert recursive is False
        return iter(
            [(nested, True), (selected, False)] if path == root else []
        )

    monkeypatch.setattr(
        client,
        "_list_dir",
        list_dir,
    )

    fb = file_browser(initial_path=root)

    response = fb._list_directory(ListDirectoryArgs(path=str(root)))
    assert [file["name"] for file in response.files] == [
        "nested",
        "selected.txt",
    ]
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(root.parent)))


def test_restrict_navigation_defaults_true(tmp_path: Path) -> None:
    fb = file_browser(initial_path=tmp_path)

    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(tmp_path.parent)))
    assert fb._component_args["restrict-navigation"] is True


def test_restrict_navigation_false_allows_parent_navigation(
    tmp_path: Path,
) -> None:
    fb = file_browser(initial_path=tmp_path, restrict_navigation=False)

    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path.parent)))
    assert isinstance(response, ListDirectoryResponse)
    assert fb._component_args["restrict-navigation"] is False


def test_warns_once_for_default_root(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.chdir(tmp_path)
    monkeypatch.setattr(fb_module, "_WARNED_DEFAULT_ROOT", False)
    calls: list[tuple[Any, ...]] = []
    monkeypatch.setattr(
        fb_module.LOGGER, "warning", lambda *args: calls.append(args)
    )

    file_browser()
    file_browser()

    assert len(calls) == 1
    assert "initial_path" in calls[0][0]


def test_warns_for_default_root_with_restricted_value(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    selected = tmp_path / "selected.txt"
    selected.touch()
    monkeypatch.chdir(tmp_path)
    monkeypatch.setattr(fb_module, "_WARNED_DEFAULT_ROOT", False)
    calls: list[tuple[Any, ...]] = []
    monkeypatch.setattr(
        fb_module.LOGGER, "warning", lambda *args: calls.append(args)
    )

    file_browser(value=selected, restrict_navigation=True)

    assert len(calls) == 1
    assert "initial_path" in calls[0][0]


def test_no_warn_with_explicit_initial_path(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.setattr(fb_module, "_WARNED_DEFAULT_ROOT", False)
    calls: list[tuple[Any, ...]] = []
    monkeypatch.setattr(
        fb_module.LOGGER, "warning", lambda *args: calls.append(args)
    )

    file_browser(initial_path=tmp_path)

    assert calls == []


def test_no_warn_when_navigation_is_unrestricted(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.chdir(tmp_path)
    monkeypatch.setattr(fb_module, "_WARNED_DEFAULT_ROOT", False)
    calls: list[tuple[Any, ...]] = []
    monkeypatch.setattr(
        fb_module.LOGGER, "warning", lambda *args: calls.append(args)
    )

    file_browser(restrict_navigation=False)

    assert calls == []


def test_no_warn_with_unrestricted_value(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.chdir(tmp_path)
    selected = tmp_path / "f.txt"
    selected.write_text("x")
    monkeypatch.setattr(fb_module, "_WARNED_DEFAULT_ROOT", False)
    calls: list[tuple[Any, ...]] = []
    monkeypatch.setattr(
        fb_module.LOGGER, "warning", lambda *args: calls.append(args)
    )

    file_browser(value=str(selected), restrict_navigation=False)

    assert calls == []


def test_file_browser_init(tmp_path: Path) -> None:
    # Use tmp_path fixture for testing
    fb = file_browser(initial_path=tmp_path)
    assert isinstance(fb._initial_path, Path)
    assert str(fb._initial_path) == str(normalize_path(tmp_path))
    assert fb._selection_mode == frozenset({"file"})
    assert fb._filetypes == set()
    assert fb._restrict_navigation is True

    # Test with custom filetypes
    custom_filetypes = [".txt", ".csv"]
    fb = file_browser(
        initial_path=tmp_path,
        filetypes=custom_filetypes,
        selection_mode="directory",
        restrict_navigation=True,
    )
    assert fb._initial_path == normalize_path(tmp_path)
    assert fb._filetypes == set(custom_filetypes)
    assert fb._selection_mode == frozenset({"directory"})
    assert fb._restrict_navigation is True


def test_file_browser_default_value(tmp_path: Path) -> None:
    first = tmp_path / "first.txt"
    second = tmp_path / "second.txt"
    first.touch()
    second.touch()

    fb = file_browser(initial_path=tmp_path, value=[first, str(second)])

    assert [file.path for file in fb.value] == [first, second]
    assert [file.name for file in fb.value] == ["first.txt", "second.txt"]


def test_file_browser_infers_initial_path_from_default_value(
    tmp_path: Path,
) -> None:
    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()

    fb = file_browser(value=selected, restrict_navigation=False)

    assert fb._initial_path == selected.parent


def test_file_browser_infers_initial_path_from_string_value(
    tmp_path: Path,
) -> None:
    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()

    fb = file_browser(value=str(selected), restrict_navigation=False)

    assert fb._initial_path == selected.parent


def test_file_browser_infers_common_initial_path_from_default_values(
    tmp_path: Path,
) -> None:
    first = tmp_path / "nested" / "first" / "selected.txt"
    second = tmp_path / "nested" / "second" / "selected.txt"
    first.parent.mkdir(parents=True)
    second.parent.mkdir(parents=True)
    first.touch()
    second.touch()

    fb = file_browser(value=[first, second], restrict_navigation=False)

    assert fb._initial_path == tmp_path / "nested"


@pytest.mark.skipif(
    sys.version_info <= (3, 12), reason="Only works with Python 3.12+"
)
def test_file_browser_infers_custom_path_class_and_client(
    tmp_path: Path,
) -> None:
    class CustomPathWithClient(Path):
        def __init__(self, path: Path, client: Any | None = None) -> None:
            super().__init__(path)
            self.client = client

    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()

    fb = file_browser(
        value=CustomPathWithClient(selected, client="custom_client"),
        restrict_navigation=False,
    )

    assert isinstance(fb._initial_path, CustomPathWithClient)
    assert isinstance(fb.path(), CustomPathWithClient)
    assert fb.path().client == "custom_client"


def test_file_browser_explicit_initial_path_takes_precedence(
    tmp_path: Path,
) -> None:
    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()

    fb = file_browser(initial_path=tmp_path, value=selected)

    assert fb._initial_path == tmp_path


def test_restricted_file_browser_does_not_infer_initial_path(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()
    monkeypatch.chdir(tmp_path)

    fb = file_browser(value=selected, restrict_navigation=True)

    assert fb._initial_path == tmp_path


def test_restricted_file_browser_accepts_symlinked_cwd_value(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    real_directory = tmp_path / "real"
    real_directory.mkdir()
    symlinked_directory = tmp_path / "symlink"
    try:
        symlinked_directory.symlink_to(real_directory)
    except OSError:
        pytest.skip("Cannot create symlinks on this system")

    selected = symlinked_directory / "selected.txt"
    selected.touch()
    monkeypatch.chdir(symlinked_directory)

    fb = file_browser(value=selected, restrict_navigation=True)

    assert fb.path() == selected


def test_restricted_file_browser_rejects_unreachable_default_value(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    root = tmp_path / "root"
    root.mkdir()
    selected = tmp_path / "outside.txt"
    selected.touch()
    monkeypatch.chdir(root)

    with pytest.raises(
        ValueError, match="outside the restricted initial path"
    ):
        file_browser(value=selected, restrict_navigation=True)


def test_unrestricted_file_browser_allows_default_value_outside_initial_path(
    tmp_path: Path,
) -> None:
    root = tmp_path / "root"
    root.mkdir()
    selected = tmp_path / "outside.txt"
    selected.touch()
    fb = file_browser(
        initial_path=root,
        value=selected,
        restrict_navigation=False,
    )

    assert fb.path() == selected


def test_restricted_file_browser_accepts_explicit_reachable_default_value(
    tmp_path: Path,
) -> None:
    selected = tmp_path / "nested" / "selected.txt"
    selected.parent.mkdir()
    selected.touch()

    fb = file_browser(
        initial_path=tmp_path,
        value=selected,
        restrict_navigation=True,
    )

    assert fb._initial_path == tmp_path


def test_file_browser_single_default_value(tmp_path: Path) -> None:
    selected = tmp_path / "selected.txt"
    selected.touch()

    fb = file_browser(initial_path=tmp_path, value=selected, multiple=False)

    assert fb.path() == selected


def test_file_browser_rejects_missing_default_value(tmp_path: Path) -> None:
    missing = tmp_path / "missing.txt"

    with pytest.raises(ValueError, match="does not exist"):
        file_browser(initial_path=tmp_path, value=missing)


def test_file_browser_rejects_multiple_default_values(
    tmp_path: Path,
) -> None:
    first = tmp_path / "first.txt"
    second = tmp_path / "second.txt"
    first.touch()
    second.touch()

    with pytest.raises(ValueError, match="multiple=False"):
        file_browser(
            initial_path=tmp_path,
            value=[first, second],
            multiple=False,
        )


def test_file_browser_rejects_empty_string_value(tmp_path: Path) -> None:
    with pytest.raises(ValueError, match='Invalid value=""') as error:
        file_browser(initial_path=tmp_path, value="")

    assert str(tmp_path) not in str(error.value)


def test_file_browser_rejects_empty_string_value_for_any_selection_mode(
    tmp_path: Path,
) -> None:
    with pytest.raises(ValueError, match='Invalid value=""'):
        file_browser(initial_path=tmp_path, value="", selection_mode="all")


def test_file_browser_rejects_empty_string_among_valid_values(
    tmp_path: Path,
) -> None:
    selected = tmp_path / "selected.txt"
    selected.touch()

    with pytest.raises(ValueError, match=r'Invalid value\[1\]=""'):
        file_browser(initial_path=tmp_path, value=[selected, ""])


def test_file_browser_accepts_relative_string_value(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    selected = tmp_path / "selected.txt"
    selected.touch()
    monkeypatch.chdir(tmp_path)

    fb = file_browser(value="selected.txt")

    assert fb.path() == normalize_path(Path("selected.txt"))


def test_file_browser_rejects_default_value_of_wrong_kind(
    tmp_path: Path,
) -> None:
    directory = tmp_path / "directory"
    directory.mkdir()

    with pytest.raises(ValueError, match="selection_mode"):
        file_browser(initial_path=tmp_path, value=directory)


def test_list_directory() -> None:
    fb = file_browser(
        initial_path=Path.cwd(), filetypes=[".txt"], selection_mode="file"
    )
    response = fb._list_directory(ListDirectoryArgs(path=str(Path.cwd())))
    assert isinstance(response, ListDirectoryResponse)
    assert isinstance(response.total_count, int)
    assert isinstance(response.is_truncated, bool)
    assert hasattr(response, "total_count")
    assert hasattr(response, "is_truncated")

    for file_info in response.files:
        assert file_info["is_directory"] or file_info["path"].endswith(
            tuple(fb._filetypes)
        )


def test_navigation_restriction() -> None:
    fb = file_browser(initial_path=Path.cwd(), restrict_navigation=True)
    with pytest.raises(RuntimeError) as e:
        fb._list_directory(ListDirectoryArgs(path=str(Path.cwd().parent)))
    assert "Navigation is restricted" in str(e.value)


def test_navigation_restriction_allows_subdirectory(tmp_path: Path) -> None:
    """Navigation within the initial directory must succeed."""
    root = tmp_path / "root"
    child = root / "child"
    child.mkdir(parents=True)
    (child / "file.txt").touch()

    fb = file_browser(initial_path=root, restrict_navigation=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(child)))
    assert isinstance(response, ListDirectoryResponse)
    file_names = [f["name"] for f in response.files]
    assert "file.txt" in file_names


def test_navigation_restriction_sibling(tmp_path: Path) -> None:
    """Sibling directories must be rejected, not just direct parents."""
    restricted = tmp_path / "restricted"
    sibling = tmp_path / "sibling"
    restricted.mkdir()
    sibling.mkdir()
    (sibling / "secret.txt").touch()

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(sibling)))


def test_navigation_restriction_absolute_path(tmp_path: Path) -> None:
    """Arbitrary absolute paths outside the root must be rejected."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path="/tmp"))


def test_navigation_restriction_symlink_escape(tmp_path: Path) -> None:
    """A symlink inside the restricted dir pointing outside must be rejected."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    outside = tmp_path / "outside"
    outside.mkdir()
    (outside / "secret.txt").touch()

    # Symlink lives inside restricted/ but resolves outside
    escape_link = restricted / "escape"
    try:
        escape_link.symlink_to(outside)
    except OSError:
        pytest.skip("Cannot create symlinks on this system")

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(escape_link)))


def test_navigation_restriction_symlink_loop(tmp_path: Path) -> None:
    """Circular symlinks must not hang or silently succeed."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()

    link_a = restricted / "link_a"
    link_b = restricted / "link_b"
    try:
        link_a.symlink_to(link_b)
        link_b.symlink_to(link_a)
    except OSError:
        pytest.skip("Cannot create symlinks on this system")

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(link_a)))


def test_navigation_restriction_internal_symlink(tmp_path: Path) -> None:
    """A symlink that resolves to a path inside the restricted dir is allowed."""
    restricted = tmp_path / "restricted"
    child = restricted / "child"
    child.mkdir(parents=True)
    (child / "file.txt").touch()

    # Symlink inside restricted/ pointing to another subdir of restricted/
    alias = restricted / "alias"
    try:
        alias.symlink_to(child)
    except OSError:
        pytest.skip("Cannot create symlinks on this system")

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(alias)))
    assert isinstance(response, ListDirectoryResponse)
    file_names = [f["name"] for f in response.files]
    assert "file.txt" in file_names


def test_navigation_restriction_dotdot_escape(tmp_path: Path) -> None:
    """Path traversal via .. components must be caught."""
    restricted = tmp_path / "restricted"
    sibling = tmp_path / "sibling"
    restricted.mkdir()
    sibling.mkdir()
    (sibling / "secret.txt").touch()

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    traversal = str(restricted / ".." / "sibling")
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=traversal))


def test_missing_path_inside_root_reports_not_found(tmp_path: Path) -> None:
    """A missing path inside the root reports not-found, not a restriction."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    missing = restricted / "missing"

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(FileNotFoundError, match="does not exist"):
        fb._list_directory(ListDirectoryArgs(path=str(missing)))


def test_missing_path_outside_root_reports_restriction(tmp_path: Path) -> None:
    """A missing path outside the root still reports a restriction."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    missing = tmp_path / "outside" / "missing"

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._list_directory(ListDirectoryArgs(path=str(missing)))


def test_missing_path_without_restriction_reports_not_found(
    tmp_path: Path,
) -> None:
    """Unrestricted navigation to a missing path reports not-found."""
    fb = file_browser(initial_path=tmp_path, restrict_navigation=False)
    with pytest.raises(FileNotFoundError, match="does not exist"):
        fb._list_directory(ListDirectoryArgs(path=str(tmp_path / "missing")))


def test_restricted_update_rejects_value_outside_root(tmp_path: Path) -> None:
    """A frontend value pointing outside the root must be rejected.

    `_list_directory` blocks browsing outside `initial_path`, but the value can
    also be set directly through the `set_ui_element_value` API, which calls
    `_update` -> `_convert_value`. That path must enforce the same restriction,
    otherwise an app viewer can read any file the server can (MO-7713).
    """
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    outside = tmp_path / "outside"
    outside.mkdir()
    secret = outside / "secret.txt"
    secret.write_text("secret data here")

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    with pytest.raises(RuntimeError, match="Navigation is restricted"):
        fb._update(
            [
                {
                    "id": str(secret),
                    "path": str(secret),
                    "name": secret.name,
                    "is_directory": False,
                }
            ]
        )


def test_restricted_update_accepts_value_within_root(tmp_path: Path) -> None:
    """A frontend value inside the root is still accepted after the fix."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    reachable = restricted / "data.txt"
    reachable.write_text("ok")

    fb = file_browser(initial_path=restricted, restrict_navigation=True)
    fb._update(
        [
            {
                "id": str(reachable),
                "path": str(reachable),
                "name": reachable.name,
                "is_directory": False,
            }
        ]
    )
    assert fb.path() == reachable


def test_unrestricted_update_accepts_value_outside_root(
    tmp_path: Path,
) -> None:
    """Without restriction, values outside the root remain allowed."""
    restricted = tmp_path / "restricted"
    restricted.mkdir()
    outside = tmp_path / "outside"
    outside.mkdir()
    target = outside / "data.txt"
    target.write_text("ok")

    fb = file_browser(initial_path=restricted, restrict_navigation=False)
    fb._update(
        [
            {
                "id": str(target),
                "path": str(target),
                "name": target.name,
                "is_directory": False,
            }
        ]
    )
    assert fb.path() == target


def test_name_method() -> None:
    fb = file_browser(initial_path=Path.cwd())
    fb._value = [
        FileBrowserFileInfo(
            id="1",
            path=Path("/some/path/file.txt"),
            name="file.txt",
            is_directory=False,
        )
    ]
    assert fb.name(0) == "file.txt"
    assert fb.name(1) is None


def test_path_method() -> None:
    fb = file_browser(initial_path=Path.cwd())
    fb._value = [
        FileBrowserFileInfo(
            id="1",
            path=Path("/some/path/file.txt"),
            name="file.txt",
            is_directory=False,
        )
    ]
    assert fb.path(0) == Path("/some/path/file.txt")
    assert fb.path(1) is None


def test_natural_sorting(tmp_path: Path) -> None:
    """Test that files are sorted using natural sort order."""
    # Create test files with names that should be naturally sorted
    test_files = [
        "file10.txt",
        "file2.txt",
        "file1.txt",
        "file20.txt",
        "fileB.txt",
        "fileA.txt",
        "file100.txt",
    ]

    for filename in test_files:
        (tmp_path / filename).touch()

    fb = file_browser(initial_path=tmp_path)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # Extract file names from response
    file_names = [f["name"] for f in response.files if not f["is_directory"]]

    # Expected natural sort order
    expected_order = [
        "file1.txt",
        "file2.txt",
        "file10.txt",
        "file20.txt",
        "file100.txt",
        "fileA.txt",
        "fileB.txt",
    ]

    assert file_names == expected_order


def test_directories_sorted_before_files(tmp_path: Path) -> None:
    """Test that directories are sorted before files."""
    # Create test directories and files
    (tmp_path / "z_directory").mkdir()
    (tmp_path / "a_directory").mkdir()
    (tmp_path / "a_file.txt").touch()
    (tmp_path / "z_file.txt").touch()

    fb = file_browser(initial_path=tmp_path)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # Extract names and types
    items = [(f["name"], f["is_directory"]) for f in response.files]

    # Check that all directories come before all files
    directory_names = [name for name, is_dir in items if is_dir]
    file_names = [name for name, is_dir in items if not is_dir]

    # Directories should be sorted naturally among themselves
    assert directory_names == ["a_directory", "z_directory"]
    # Files should be sorted naturally among themselves
    assert file_names == ["a_file.txt", "z_file.txt"]

    # All directory names should come before all file names in the full list
    all_names = [name for name, _ in items]
    directory_end_index = len(directory_names)
    assert all_names[:directory_end_index] == directory_names
    assert all_names[directory_end_index:] == file_names


def test_mixed_alphanumeric_sorting(tmp_path: Path) -> None:
    """Test natural sorting with mixed alphanumeric patterns."""
    test_items = [
        ("dir100", True),  # directory
        ("dir2", True),  # directory
        ("dir10", True),  # directory
        ("file100.txt", False),  # file
        ("file2.txt", False),  # file
        ("file10.txt", False),  # file
    ]

    # Create test directories and files
    for name, is_dir in test_items:
        if is_dir:
            (tmp_path / name).mkdir()
        else:
            (tmp_path / name).touch()

    fb = file_browser(initial_path=tmp_path)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # Extract names preserving order from response
    result_names = [f["name"] for f in response.files]

    # Expected order: directories first (naturally sorted), then files (naturally sorted)
    expected_order = [
        "dir2",  # directories first, naturally sorted
        "dir10",
        "dir100",
        "file2.txt",  # files second, naturally sorted
        "file10.txt",
        "file100.txt",
    ]

    assert result_names == expected_order


@pytest.mark.skipif(
    sys.version_info <= (3, 12), reason="Only works with Python 3.12+"
)
def test_extended_path_class(tmp_path: Path) -> None:
    class CustomPath(Path):
        pass

    (tmp_path / "file.txt").touch()

    fb = file_browser(initial_path=CustomPath(tmp_path), limit=1)
    response = fb._list_directory(
        ListDirectoryArgs(path=str(tmp_path)),
    )
    assert isinstance(response, ListDirectoryResponse)
    for file_info in response.files:
        assert isinstance(file_info["path"], str)

    # Convert the value
    value = fb._convert_value(response.files)
    assert isinstance(value, tuple)
    assert len(value) == 1
    assert isinstance(value[0], FileBrowserFileInfo)
    assert isinstance(value[0].path, CustomPath)

    class CustomPathWithClient(Path):
        def __init__(self, path: Path, client: Any | None = None) -> None:
            super().__init__(path)
            self.client = client

        def resolve(self) -> CustomPathWithClient:
            return CustomPathWithClient(super().resolve(), self.client)

    fb = file_browser(
        initial_path=CustomPathWithClient(tmp_path, "custom_client")
    )
    response = fb._list_directory(
        ListDirectoryArgs(path=str(tmp_path)),
    )
    value = fb._convert_value(response.files)
    assert isinstance(value, tuple)
    assert len(value) == 1
    assert isinstance(value[0], FileBrowserFileInfo)
    assert isinstance(value[0].path, CustomPathWithClient)
    assert value[0].path.client == "custom_client"


def test_validation() -> None:
    with pytest.raises(ValueError) as e:
        file_browser(initial_path="invalid", selection_mode="invalid")  # type: ignore[arg-type]
    assert "Invalid selection_mode" in str(e.value)


def test_limit_arg(tmp_path: Path) -> None:
    """Test limit argument behavior: defaults and explicit overrides."""
    fb_default = file_browser(initial_path=tmp_path)
    assert fb_default._limit == 10000  # High limit for local filesystem

    fb_custom = file_browser(initial_path=tmp_path, limit=25)
    assert fb_custom._limit == 25

    fb_zero = file_browser(initial_path=tmp_path, limit=0)
    assert fb_zero._limit == 0


def test_is_truncated_true_when_limit_exceeded(tmp_path: Path) -> None:
    """Test is_truncated=True when directory has more files than limit."""
    # Create more files than the limit
    for i in range(10):
        (tmp_path / f"file{i}.txt").touch()

    fb = file_browser(initial_path=tmp_path, limit=5)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    assert response.is_truncated is True
    assert response.total_count == 10
    assert len(response.files) == 5


def test_is_truncated_false_when_under_limit(tmp_path: Path) -> None:
    """Test is_truncated=False when directory has fewer files than limit."""
    # Create fewer files than the limit
    for i in range(3):
        (tmp_path / f"file{i}.txt").touch()

    fb = file_browser(initial_path=tmp_path, limit=5)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    assert response.is_truncated is False
    assert response.total_count == 3
    assert len(response.files) == 3


def test_is_truncated_false_when_exactly_at_limit(tmp_path: Path) -> None:
    """Test is_truncated=False when directory has exactly limit number of files."""
    # Create exactly the limit number of files
    for i in range(5):
        (tmp_path / f"file{i}.txt").touch()

    fb = file_browser(initial_path=tmp_path, limit=5)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    assert response.is_truncated is False
    assert response.total_count == 5
    assert len(response.files) == 5


def test_total_count_includes_all_items(tmp_path: Path) -> None:
    """Test that total_count reflects all files in directory, not just displayed ones."""
    # Create mix of files and directories
    for i in range(8):
        (tmp_path / f"file{i}.txt").touch()
    for i in range(3):
        (tmp_path / f"dir{i}").mkdir()

    fb = file_browser(initial_path=tmp_path, limit=5)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    assert response.total_count == 11  # All files and directories
    assert len(response.files) == 5  # Only displayed items
    assert response.is_truncated is True


def test_is_truncated_with_filetype_filtering_edge_case(
    tmp_path: Path,
) -> None:
    """Test is_truncated when filtering creates ambiguity about remaining files."""
    # Create files where filtering matters for truncation detection
    (tmp_path / "file1.txt").touch()
    (tmp_path / "file2.txt").touch()
    (tmp_path / "file3.txt").touch()
    (tmp_path / "file4.py").touch()
    (tmp_path / "file5.py").touch()

    fb = file_browser(initial_path=tmp_path, filetypes=[".txt"], limit=2)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # We should show two .txt files, but there's a third .txt file we didn't process
    assert response.total_count == 5
    assert len(response.files) == 2
    assert response.is_truncated is True


def test_ignore_empty_dirs_initialization(tmp_path: Path) -> None:
    """Test that ignore_empty_dirs parameter is properly initialized."""
    # Creates:
    # tmp_path/  (empty directory for initialization testing)

    # Default should be False
    fb_default = file_browser(initial_path=tmp_path)
    assert fb_default._ignore_empty_dirs is False

    # Explicit True
    fb_true = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    assert fb_true._ignore_empty_dirs is True

    # Explicit False
    fb_false = file_browser(initial_path=tmp_path, ignore_empty_dirs=False)
    assert fb_false._ignore_empty_dirs is False


def test_ignore_empty_dirs_with_empty_directory(tmp_path: Path) -> None:
    """Test that empty directories are hidden when ignore_empty_dirs=True."""
    # Create structure with empty directories
    # /
    # ├── empty_dir / (empty directory)
    # ├── another_empty / (empty directory)
    # └── file.txt(empty file)

    (tmp_path / "empty_dir").mkdir()
    (tmp_path / "another_empty").mkdir()
    (tmp_path / "file.txt").touch()

    # Without ignore_empty_dirs (should show empty directories)
    fb_false = file_browser(initial_path=tmp_path, ignore_empty_dirs=False)
    response_false = fb_false._list_directory(
        ListDirectoryArgs(path=str(tmp_path))
    )

    directory_names = [
        f["name"] for f in response_false.files if f["is_directory"]
    ]
    file_names = [
        f["name"] for f in response_false.files if not f["is_directory"]
    ]

    assert "empty_dir" in directory_names
    assert "another_empty" in directory_names
    assert "file.txt" in file_names

    # With ignore_empty_dirs (should hide empty directories)
    fb_true = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response_true = fb_true._list_directory(
        ListDirectoryArgs(path=str(tmp_path))
    )

    directory_names = [
        f["name"] for f in response_true.files if f["is_directory"]
    ]
    file_names = [
        f["name"] for f in response_true.files if not f["is_directory"]
    ]

    assert "empty_dir" not in directory_names
    assert "another_empty" not in directory_names
    assert "file.txt" in file_names


def test_ignore_empty_dirs_with_nested_empty_directories(
    tmp_path: Path,
) -> None:
    """Test that deeply nested empty directories are hidden."""
    # Creates:
    # tmp_path/
    # ├── level1/
    # │   └── level2/
    # │       └── level3/          (nested empty structure)
    # └── non_empty/
    #     └── file.txt             (directory with files)

    # Create nested empty directory structure
    nested_path = tmp_path / "level1" / "level2" / "level3"
    nested_path.mkdir(parents=True)

    # Create a non-empty directory for comparison
    non_empty_dir = tmp_path / "non_empty"
    non_empty_dir.mkdir()
    (non_empty_dir / "file.txt").touch()

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should hide the nested empty structure but show the non-empty directory
    assert "level1" not in directory_names
    assert "non_empty" in directory_names


def test_ignore_empty_dirs_with_files_in_subdirectories(
    tmp_path: Path,
) -> None:
    """Test that directories with files in subdirectories are shown."""
    # Creates:
    # tmp_path/
    # ├── has_files/
    # │   └── nested/
    # │       └── deep/
    # │           └── deep_file.txt    (file buried deep inside)
    # └── empty_dir/                   (truly empty)

    # Create directory structure with files deep inside
    deep_dir = tmp_path / "has_files" / "nested" / "deep"
    deep_dir.mkdir(parents=True)
    (deep_dir / "deep_file.txt").touch()

    # Create empty directory for comparison
    (tmp_path / "empty_dir").mkdir()

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show directory that has files somewhere inside
    assert "has_files" in directory_names
    # Should hide truly empty directory
    assert "empty_dir" not in directory_names


def test_ignore_empty_dirs_respects_filetype_filter(tmp_path: Path) -> None:
    """Test that ignore_empty_dirs respects filetype filtering."""
    # Creates:
    # tmp_path/
    # ├── python_only/
    # │   └── script.py        (has files, but wrong type)
    # ├── text_files/
    # │   └── document.txt     (has files of correct type)
    # └── empty_dir/           (truly empty)

    # Create directory with only .py files (no .txt files)
    py_dir = tmp_path / "python_only"
    py_dir.mkdir()
    (py_dir / "script.py").touch()

    # Create directory with .txt files
    txt_dir = tmp_path / "text_files"
    txt_dir.mkdir()
    (txt_dir / "document.txt").touch()

    # Create empty directory
    (tmp_path / "empty_dir").mkdir()

    # Filter for .txt files only with ignore_empty_dirs=True
    fb = file_browser(
        initial_path=tmp_path, filetypes=[".txt"], ignore_empty_dirs=True
    )
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show directory with .txt files
    assert "text_files" in directory_names
    # Should hide directory with only .py files (filtered out)
    assert "python_only" not in directory_names
    # Should hide empty directory
    assert "empty_dir" not in directory_names


def test_ignore_empty_dirs_mixed_with_files(tmp_path: Path) -> None:
    """Test ignore_empty_dirs behavior in a directory with mixed content."""
    # Creates:
    # tmp_path/
    # ├── root_file.txt        (file at root level)
    # ├── good_dir/
    # │   └── subfile.txt      (directory with files)
    # ├── empty_dir/           (truly empty)
    # └── nested_empty/
    #     └── level2/          (nested empty structure)

    # Create files at root level
    (tmp_path / "root_file.txt").touch()

    # Create non-empty subdirectory
    good_dir = tmp_path / "good_dir"
    good_dir.mkdir()
    (good_dir / "subfile.txt").touch()

    # Create empty subdirectory
    (tmp_path / "empty_dir").mkdir()

    # Create directory with nested empty directories only
    nested_empty = tmp_path / "nested_empty" / "level2"
    nested_empty.mkdir(parents=True)

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # Separate directories and files
    directory_names = [f["name"] for f in response.files if f["is_directory"]]
    file_names = [f["name"] for f in response.files if not f["is_directory"]]

    # Should show non-empty directory and root file
    assert "good_dir" in directory_names
    assert "root_file.txt" in file_names

    # Should hide empty directories
    assert "empty_dir" not in directory_names
    assert "nested_empty" not in directory_names


def test_ignore_empty_dirs_directory_selection_mode(tmp_path: Path) -> None:
    """Test ignore_empty_dirs with selection_mode='directory'."""
    # Creates:
    # tmp_path/
    # ├── empty_dir/           (empty directory)
    # ├── good_dir/
    # │   └── file.txt         (directory with files)
    # └── file.txt             (file - filtered out in directory mode)

    # Create empty directory
    (tmp_path / "empty_dir").mkdir()

    # Create directory with files
    good_dir = tmp_path / "good_dir"
    good_dir.mkdir()
    (good_dir / "file.txt").touch()

    # Create a file (should be filtered out in directory mode)
    (tmp_path / "file.txt").touch()

    fb = file_browser(
        initial_path=tmp_path,
        selection_mode="directory",
        ignore_empty_dirs=True,
    )
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    # All results should be directories (selection_mode filters files)
    for item in response.files:
        assert item["is_directory"] is True

    directory_names = [f["name"] for f in response.files]

    # Should show non-empty directory
    assert "good_dir" in directory_names
    # Should hide empty directory
    assert "empty_dir" not in directory_names


def test_ignore_empty_dirs_respects_max_depth(tmp_path: Path) -> None:
    """Test that recursion depth is limited to prevent stack overflow."""
    # Creates:
    # tmp_path/
    # ├── shallow_with_files/
    # │   └── file.txt         (file at shallow depth)
    # ├── deep_structure/
    # │   └── level1/
    # │       └── level2/
    # │           └── ... (many levels)
    # │               └── deep_file.txt (file beyond max_depth)
    # └── empty_dir/           (truly empty)

    # Create shallow directory with files
    shallow_dir = tmp_path / "shallow_with_files"
    shallow_dir.mkdir()
    (shallow_dir / "file.txt").touch()

    # Create very deep directory structure (beyond max_depth)
    deep_path = tmp_path / "deep_structure"
    current = deep_path
    # Create 102 levels deep (beyond default max_depth of 100)
    for i in range(102):
        current = current / f"level{i}"
    current.mkdir(parents=True)
    (current / "deep_file.txt").touch()

    # Create empty directory for comparison
    (tmp_path / "empty_dir").mkdir()

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show shallow directory with files
    assert "shallow_with_files" in directory_names
    # Should show deep structure (assumes has files when max_depth reached)
    assert "deep_structure" in directory_names
    # Should hide empty directory
    assert "empty_dir" not in directory_names


def test_ignore_empty_dirs_max_depth_boundary_conditions(
    tmp_path: Path,
) -> None:
    """Test boundary conditions around max_depth limit."""
    # Creates:
    # tmp_path/
    # ├── depth_100_with_file/
    # │   └── level0/level1/.../level99/
    # │       └── file.txt         (file at exactly depth 100)
    # ├── depth_101_with_file/
    # │   └── level0/level1/.../level100/
    # │       └── file.txt         (file at depth 101 - beyond limit)
    # ├── depth_100_empty/
    # │   └── level0/level1/.../level99/  (empty at depth 100)
    # └── depth_101_empty/
    #     └── level0/level1/.../level100/ (empty at depth 101 - beyond limit)

    # Test case 1: File at exactly depth 100 (should be found)
    depth_100_with_file = tmp_path / "depth_100_with_file"
    current = depth_100_with_file
    for i in range(100):  # Create 100 levels deep
        current = current / f"level{i}"
    current.mkdir(parents=True)
    (current / "file.txt").touch()

    # Test case 2: File at depth 101 (beyond limit, should assume has files)
    depth_101_with_file = tmp_path / "depth_101_with_file"
    current = depth_101_with_file
    for i in range(101):  # Create 101 levels deep
        current = current / f"level{i}"
    current.mkdir(parents=True)
    (current / "file.txt").touch()

    # Test case 3: Empty at exactly depth 99 (should be detected as empty)
    depth_99_empty = tmp_path / "depth_99_empty"
    current = depth_99_empty
    for i in range(99):  # Create 99 levels deep (within limit)
        current = current / f"level{i}"
    current.mkdir(parents=True)  # No file created

    # Test case 4: Empty at depth 100 (at limit, should assume has files)
    depth_100_empty = tmp_path / "depth_100_empty"
    current = depth_100_empty
    for i in range(100):
        current = current / f"level{i}"
    current.mkdir(parents=True)  # No file created

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show directory with file at depth 100 (within limit)
    assert "depth_100_with_file" in directory_names
    # Should show directory with file at depth 101 (beyond limit, assumes has files)
    assert "depth_101_with_file" in directory_names
    # Should hide empty directory at depth 99 (within limit, detected as empty)
    assert "depth_99_empty" not in directory_names
    # Should show empty directory at depth 100 (at limit, assumes has files for safety)
    assert "depth_100_empty" in directory_names


def test_ignore_empty_dirs_case_insensitive_filetypes(tmp_path: Path) -> None:
    """Test that filetype filtering is case-insensitive."""
    # Creates:
    # tmp_path/
    # ├── mixed_case_files/
    # │   ├── document.TXT     (uppercase extension)
    # │   ├── script.Py        (mixed case extension)
    # │   └── data.CSV         (uppercase extension)
    # ├── wrong_type_files/
    # │   └── archive.zip      (different extension)
    # └── empty_dir/           (truly empty)

    # Create directory with mixed case extensions
    mixed_case_dir = tmp_path / "mixed_case_files"
    mixed_case_dir.mkdir()
    (mixed_case_dir / "document.TXT").touch()  # Uppercase
    (mixed_case_dir / "script.Py").touch()  # Mixed case
    (mixed_case_dir / "data.CSV").touch()  # Uppercase

    # Create directory with wrong file type
    wrong_type_dir = tmp_path / "wrong_type_files"
    wrong_type_dir.mkdir()
    (wrong_type_dir / "archive.zip").touch()

    # Create empty directory
    (tmp_path / "empty_dir").mkdir()

    # Test with lowercase filetypes and mixed input formats
    fb = file_browser(
        initial_path=tmp_path,
        filetypes=[
            "txt",
            ".py",
            ".CSV",
        ],  # Mixed formats: no dot, dot, uppercase
        ignore_empty_dirs=True,
    )
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]
    file_names = [f["name"] for f in response.files if not f["is_directory"]]

    # Should show directory with mixed case matching files
    assert "mixed_case_files" in directory_names
    # Should hide directory with non-matching file types
    assert "wrong_type_files" not in directory_names
    # Should hide empty directory
    assert "empty_dir" not in directory_names

    # Also test direct file listing to verify case-insensitive matching
    fb_direct = file_browser(
        initial_path=mixed_case_dir,
        filetypes=["txt", ".py", ".csv"],  # All lowercase
    )
    response_direct = fb_direct._list_directory(
        ListDirectoryArgs(path=str(mixed_case_dir))
    )
    direct_files = [
        f["name"] for f in response_direct.files if not f["is_directory"]
    ]

    # Should show all files despite case differences
    assert "document.TXT" in direct_files
    assert "script.Py" in direct_files
    assert "data.CSV" in direct_files


def test_ignore_empty_dirs_skips_directory_symlinks(tmp_path: Path) -> None:
    """Test that directory symlinks are skipped to prevent infinite loops."""
    # Creates:
    # tmp_path/
    # ├── real_dir/
    # │   └── file.txt         (real directory with files)
    # ├── symlink_to_real_dir@ -> real_dir/  (symlink to real directory)
    # ├── broken_symlink@     (broken symlink)
    # └── empty_dir/           (truly empty)

    # Create real directory with files
    real_dir = tmp_path / "real_dir"
    real_dir.mkdir()
    (real_dir / "file.txt").touch()

    # Create symlink to real directory
    symlink_dir = tmp_path / "symlink_to_real_dir"
    symlink_dir.symlink_to(real_dir)

    # Create broken symlink
    broken_symlink = tmp_path / "broken_symlink"
    broken_symlink.symlink_to(tmp_path / "nonexistent")

    # Create empty directory
    (tmp_path / "empty_dir").mkdir()

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show real directory with files
    assert "real_dir" in directory_names
    # Should show valid directory symlinks (they're not recursively checked, so treated as potentially having content)
    assert "symlink_to_real_dir" in directory_names
    # Broken symlinks may not appear as directories, so we don't test for them
    # Should hide empty directory
    assert "empty_dir" not in directory_names


def test_ignore_empty_dirs_symlink_loop_protection(tmp_path: Path) -> None:
    """Test protection against symlink loops in deep directory structures."""
    # Creates:
    # tmp_path/
    # ├── loop_start/
    # │   ├── level1/
    # │   │   ├── level2/
    # │   │   │   └── back_to_start@ -> ../../../loop_start/  (creates loop)
    # │   │   └── real_file.txt    (file in the structure)
    # │   └── file.txt             (file at top level)
    # └── empty_dir/               (truly empty)

    # Create directory structure with potential for loops
    loop_start = tmp_path / "loop_start"
    loop_start.mkdir()
    (loop_start / "file.txt").touch()

    level1 = loop_start / "level1"
    level1.mkdir()

    level2 = level1 / "level2"
    level2.mkdir()
    (level1 / "real_file.txt").touch()  # Add file to make structure non-empty

    # Create symlink that would cause infinite loop
    loop_symlink = level2 / "back_to_start"
    loop_symlink.symlink_to(loop_start)

    # Create empty directory
    (tmp_path / "empty_dir").mkdir()

    fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
    response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    directory_names = [f["name"] for f in response.files if f["is_directory"]]

    # Should show directory with files (symlinks are skipped so no infinite loop)
    assert "loop_start" in directory_names
    # Should hide empty directory
    assert "empty_dir" not in directory_names

    # Test should complete without hanging (no infinite loop)


def test_file_browser_symlink(tmp_path: Path) -> None:
    """Test that file browser doesn't follow symlinks outside initial directory."""
    # Create a safe directory inside temp
    safe_dir = tmp_path / "safe"
    safe_dir.mkdir()

    # Create a file in the safe directory
    safe_file = safe_dir / "safe.txt"
    safe_file.write_text("safe content")

    # Create a directory outside that we don't want to access
    outside_dir = tmp_path / "outside"
    outside_dir.mkdir()
    secret_file = outside_dir / "secret.txt"
    secret_file.write_text("secret content")

    # Create a symlink inside safe_dir that points outside
    symlink_to_outside = safe_dir / "link_to_outside"
    try:
        symlink_to_outside.symlink_to(outside_dir)
    except OSError:
        # On Windows, creating symlinks might require admin privileges
        pytest.skip("Cannot create symlinks on this system")

    # Create file browser restricted to safe_dir
    fb = file_browser(initial_path=safe_dir, restrict_navigation=True)

    # The initial path should not have followed the symlink
    # It should be the normalized path, not resolved
    expected_initial = normalize_path(safe_dir)
    assert fb._initial_path == expected_initial

    # List directory - should see the symlink but as a directory
    response = fb._list_directory(ListDirectoryArgs(path=str(safe_dir)))

    file_names = [f["name"] for f in response.files]
    assert "safe.txt" in file_names
    # The symlink should be visible but treated as a directory
    assert "link_to_outside" in file_names


def test_file_browser_normalize_path_not_resolve(tmp_path: Path) -> None:
    """Test that file browser uses normalize_path, not resolve."""
    # Create a real directory
    real_dir = tmp_path / "real_directory"
    real_dir.mkdir()

    # Create a file in the real directory
    real_file = real_dir / "test.txt"
    real_file.write_text("test content")

    # Create a symlink to the real directory
    symlink_dir = tmp_path / "symlinked_directory"
    try:
        symlink_dir.symlink_to(real_dir)
    except OSError:
        # On Windows, creating symlinks might require admin privileges
        pytest.skip("Cannot create symlinks on this system")

    # Create file browser with symlinked directory
    fb = file_browser(initial_path=symlink_dir)

    # The initial path should contain "symlinked_directory"
    # NOT "real_directory" (which is what resolve() would give)
    assert "symlinked_directory" in str(fb._initial_path)
    assert "real_directory" not in str(fb._initial_path)


def test_file_browser_path_with_parent_references(tmp_path: Path) -> None:
    """Test that file browser normalizes paths with .. components."""
    # Create nested directories
    nested = tmp_path / "level1" / "level2"
    nested.mkdir(parents=True)

    # Create a file
    test_file = nested / "test.txt"
    test_file.write_text("content")

    # Create path with .. that goes up and back down
    path_with_parent = tmp_path / "level1" / "level2" / ".." / "level2"

    # Create file browser - should normalize the path
    fb = file_browser(initial_path=path_with_parent)

    # The path should be normalized (no .. in it)
    assert ".." not in str(fb._initial_path)

    # Should end with level2
    assert fb._initial_path == nested


def test_file_browser_relative_path_normalization(tmp_path: Path) -> None:
    """Test that file browser normalizes relative paths to absolute."""
    # Create a subdirectory
    sub_dir = tmp_path / "subdir"
    sub_dir.mkdir()

    # Save current directory and change to tmp_path
    original_cwd = Path.cwd()
    try:
        os.chdir(tmp_path)

        # Create file browser with relative path
        fb = file_browser(initial_path="./subdir")

        # Should be absolute now
        assert fb._initial_path.is_absolute()
        assert fb._initial_path == sub_dir

    finally:
        # Restore original directory
        os.chdir(original_cwd)


def test_file_browser_relative_path_sent_to_frontend_as_absolute(
    tmp_path: Path,
) -> None:
    """Test that the initial-path arg sent to the frontend is always absolute."""
    sub_dir = tmp_path / "subdir"
    sub_dir.mkdir()
    (sub_dir / "file.txt").touch()

    original_cwd = Path.cwd()
    try:
        os.chdir(tmp_path)

        for rel_path in ["subdir", "./subdir", Path("subdir")]:
            fb = file_browser(initial_path=rel_path, restrict_navigation=False)
            initial_path_arg = str(fb._component_args["initial-path"])  # pyright: ignore[reportPrivateUsage]
            assert Path(initial_path_arg).is_absolute(), (
                f"initial-path sent to frontend must be absolute, "
                f"got: {initial_path_arg!r}"
            )

            # Navigating up from the initial path should work
            parent = str(Path(initial_path_arg).parent)
            response = fb._list_directory(ListDirectoryArgs(path=parent))  # pyright: ignore[reportPrivateUsage]
            assert isinstance(response, ListDirectoryResponse)

    finally:
        os.chdir(original_cwd)


class TestNormalizeSelectionMode:
    def test_string_file(self) -> None:
        assert _normalize_selection_mode("file") == frozenset({"file"})

    def test_string_directory(self) -> None:
        assert _normalize_selection_mode("directory") == frozenset(
            {"directory"}
        )

    def test_string_all(self) -> None:
        assert _normalize_selection_mode("all") == frozenset(
            {"file", "directory"}
        )

    def test_list_single_file(self) -> None:
        assert _normalize_selection_mode(["file"]) == frozenset({"file"})

    def test_list_single_directory(self) -> None:
        assert _normalize_selection_mode(["directory"]) == frozenset(
            {"directory"}
        )

    def test_list_both(self) -> None:
        assert _normalize_selection_mode(["file", "directory"]) == frozenset(
            {"file", "directory"}
        )

    def test_list_order_independent(self) -> None:
        assert _normalize_selection_mode(["directory", "file"]) == frozenset(
            {"file", "directory"}
        )

    def test_list_dedup(self) -> None:
        assert _normalize_selection_mode(["file", "file"]) == frozenset(
            {"file"}
        )

    def test_tuple_accepted(self) -> None:
        assert _normalize_selection_mode(("file", "directory")) == frozenset(
            {"file", "directory"}
        )

    @pytest.mark.parametrize(
        "value",
        [
            "both",
            "folder",
            "",
            "FILE",
            [],
            ["both"],
            ["file", "nope"],
            ["file", 1],
            None,
            123,
        ],
    )
    def test_rejects_invalid(self, value: Any) -> None:
        with pytest.raises(ValueError):
            _normalize_selection_mode(value)


class TestSelectionModeAll:
    def test_init_all_string(self, tmp_path: Path) -> None:
        fb = file_browser(initial_path=tmp_path, selection_mode="all")
        assert fb._selection_mode == frozenset({"file", "directory"})

    def test_init_list_form(self, tmp_path: Path) -> None:
        fb = file_browser(
            initial_path=tmp_path, selection_mode=["file", "directory"]
        )
        assert fb._selection_mode == frozenset({"file", "directory"})

    def test_init_list_single(self, tmp_path: Path) -> None:
        fb = file_browser(initial_path=tmp_path, selection_mode=["directory"])
        assert fb._selection_mode == frozenset({"directory"})

    def test_init_rejects_both(self, tmp_path: Path) -> None:
        with pytest.raises(ValueError):
            file_browser(initial_path=tmp_path, selection_mode="both")  # type: ignore[arg-type]

    def test_init_rejects_empty_list(self, tmp_path: Path) -> None:
        with pytest.raises(ValueError):
            file_browser(initial_path=tmp_path, selection_mode=[])

    def test_wire_format_all(self, tmp_path: Path) -> None:
        fb = file_browser(initial_path=tmp_path, selection_mode="all")
        assert fb._component_args["selection-mode"] == "all"

    def test_wire_format_file(self, tmp_path: Path) -> None:
        fb = file_browser(initial_path=tmp_path, selection_mode="file")
        assert fb._component_args["selection-mode"] == "file"

    def test_wire_format_directory(self, tmp_path: Path) -> None:
        fb = file_browser(initial_path=tmp_path, selection_mode="directory")
        assert fb._component_args["selection-mode"] == "directory"

    def test_wire_format_list_normalized_to_all(self, tmp_path: Path) -> None:
        fb = file_browser(
            initial_path=tmp_path,
            selection_mode=["directory", "file"],
        )
        assert fb._component_args["selection-mode"] == "all"

    def test_list_directory_all_returns_files_and_dirs(
        self, tmp_path: Path
    ) -> None:
        (tmp_path / "sub").mkdir()
        (tmp_path / "a.txt").touch()
        (tmp_path / "b.parquet").touch()
        fb = file_browser(initial_path=tmp_path, selection_mode="all")
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files}
        assert names == {"sub", "a.txt", "b.parquet"}

    def test_list_directory_all_respects_filetypes_for_files(
        self, tmp_path: Path
    ) -> None:
        (tmp_path / "sub").mkdir()
        (tmp_path / "a.txt").touch()
        (tmp_path / "b.parquet").touch()
        fb = file_browser(
            initial_path=tmp_path,
            selection_mode="all",
            filetypes=[".parquet"],
        )
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files}
        assert names == {"sub", "b.parquet"}

    def test_list_directory_directory_only_unchanged(
        self, tmp_path: Path
    ) -> None:
        (tmp_path / "sub").mkdir()
        (tmp_path / "a.txt").touch()
        fb = file_browser(initial_path=tmp_path, selection_mode="directory")
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files}
        assert names == {"sub"}


class TestFilterParameter:
    def test_filter_regex_string(self, tmp_path: Path) -> None:
        """Regex string filter matches filenames."""
        (tmp_path / "report_2024.csv").touch()
        (tmp_path / "report_2025.csv").touch()
        (tmp_path / "notes.txt").touch()

        fb = file_browser(initial_path=tmp_path, filter=r"report_\d{4}\.csv")
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"report_2024.csv", "report_2025.csv"}
        assert "notes.txt" not in names

    def test_filter_compiled_pattern(self, tmp_path: Path) -> None:
        """Compiled re.Pattern works the same as a string."""
        import re as _re

        (tmp_path / "train.parquet").touch()
        (tmp_path / "test.parquet").touch()
        (tmp_path / "readme.md").touch()

        pattern = _re.compile(r"\.(parquet)$", _re.IGNORECASE)
        fb = file_browser(initial_path=tmp_path, filter=pattern)
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"train.parquet", "test.parquet"}

    def test_filter_callable(self, tmp_path: Path) -> None:
        """Callable filter receives a Path and returns bool."""
        (tmp_path / "big_file.bin").write_bytes(b"x" * 100)
        (tmp_path / "small_file.bin").write_bytes(b"x" * 10)
        (tmp_path / "tiny.txt").write_bytes(b"hi")

        fb = file_browser(
            initial_path=tmp_path,
            filter=lambda p: p.stat().st_size >= 50,
        )
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"big_file.bin"}

    def test_filter_callable_oserror_is_isolated(self, tmp_path: Path) -> None:
        """A callable that raises OSError on one file must not crash the listing.

        The offending file is treated as "no match" and the rest of the
        directory is still returned (e.g. a broken symlink shouldn't hide the
        other files).
        """
        (tmp_path / "good.txt").touch()
        (tmp_path / "bad.txt").touch()

        def flaky(path: Path) -> bool:
            if path.name == "bad.txt":
                raise OSError("broken symlink")
            return True

        fb = file_browser(initial_path=tmp_path, filter=flaky)
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"good.txt"}

    def test_filter_callable_non_oserror_propagates(
        self, tmp_path: Path
    ) -> None:
        """A non-OSError from the filter callable propagates (not swallowed)."""
        (tmp_path / "file.txt").touch()

        def boom(_path: Path) -> bool:
            raise ValueError("programming error")

        fb = file_browser(initial_path=tmp_path, filter=boom)
        with pytest.raises(ValueError, match="programming error"):
            fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))

    def test_filter_does_not_hide_directories(self, tmp_path: Path) -> None:
        """Directories are always shown regardless of filter."""
        sub = tmp_path / "subdir"
        sub.mkdir()
        (tmp_path / "file.txt").touch()

        fb = file_browser(initial_path=tmp_path, filter=r"\.csv$")
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files}
        assert "subdir" in names
        assert "file.txt" not in names

    def test_filter_and_filetypes_both_applied(self, tmp_path: Path) -> None:
        """filter and filetypes must both match (AND semantics)."""
        (tmp_path / "train_v1.csv").touch()
        (tmp_path / "train_v2.csv").touch()
        (tmp_path / "test_v1.csv").touch()
        (tmp_path / "train_v1.txt").touch()

        fb = file_browser(
            initial_path=tmp_path,
            filetypes=[".csv"],
            filter=r"^train_",
        )
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"train_v1.csv", "train_v2.csv"}

    def test_filter_none_shows_all_files(self, tmp_path: Path) -> None:
        """Default filter=None does not restrict files."""
        (tmp_path / "a.csv").touch()
        (tmp_path / "b.txt").touch()

        fb = file_browser(initial_path=tmp_path, filter=None)
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        names = {f["name"] for f in response.files if not f["is_directory"]}
        assert names == {"a.csv", "b.txt"}

    def test_filter_invalid_type_raises(self, tmp_path: Path) -> None:
        """Non-string/pattern/callable raises ValueError."""
        with pytest.raises((ValueError, TypeError)):
            file_browser(initial_path=tmp_path, filter=123)  # type: ignore[arg-type]

    def test_filter_with_ignore_empty_dirs(self, tmp_path: Path) -> None:
        """ignore_empty_dirs respects the filter when scanning recursively."""
        matched_dir = tmp_path / "matched"
        matched_dir.mkdir()
        (matched_dir / "data.csv").touch()

        unmatched_dir = tmp_path / "unmatched"
        unmatched_dir.mkdir()
        (unmatched_dir / "notes.txt").touch()

        fb = file_browser(
            initial_path=tmp_path,
            filter=r"\.csv$",
            ignore_empty_dirs=True,
        )
        response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
        dir_names = {f["name"] for f in response.files if f["is_directory"]}
        assert "matched" in dir_names
        assert "unmatched" not in dir_names