Textual DirectoryTree 檔案瀏覽器：安全路徑、非同步預覽與互動測試

uv init textual-file-browser
cd textual-file-browser
uv add "textual>=8,<9"
uv add --dev pytest pytest-asyncio

from __future__ import annotations

import asyncio
import sys
from collections.abc import Iterable
from pathlib import Path

from textual import work
from textual.app import App, ComposeResult
from textual.containers import Horizontal, Vertical
from textual.widgets import DirectoryTree, Footer, Header, Static


IGNORED_NAMES = {".git", ".venv", "__pycache__", ".pytest_cache"}
MAX_PREVIEW_BYTES = 64 * 1024
TEXT_SUFFIXES = {
    ".py", ".md", ".txt", ".toml", ".yaml", ".yml", ".json", ".csv"
}


def resolve_under_root(candidate: Path, root: Path) -> Path:
    safe_root = root.expanduser().resolve(strict=True)
    resolved = candidate.expanduser().resolve(strict=True)
    if not resolved.is_relative_to(safe_root):
        raise PermissionError(f"路徑超出允許範圍：{resolved}")
    return resolved


def read_preview(path: Path, root: Path) -> str:
    safe_path = resolve_under_root(path, root)
    if not safe_path.is_file():
        raise ValueError("選取項目不是一般檔案")
    if safe_path.suffix.lower() not in TEXT_SUFFIXES:
        return "此類型不提供文字預覽。"

    with safe_path.open("rb") as file:
        data = file.read(MAX_PREVIEW_BYTES + 1)

    truncated = len(data) > MAX_PREVIEW_BYTES
    data = data[:MAX_PREVIEW_BYTES]
    if b"\x00" in data:
        return "偵測到 binary 內容，不顯示預覽。"

    text = data.decode("utf-8", errors="replace")
    if truncated:
        text += "\n\n… 預覽已截斷 …"
    return text


class SafeDirectoryTree(DirectoryTree):
    def filter_paths(self, paths: Iterable[Path]) -> Iterable[Path]:
        return [
            path
            for path in paths
            if path.name not in IGNORED_NAMES
            and not path.name.startswith(".")
        ]


class FileBrowser(App[None]):
    TITLE = "拍拍君的安全檔案瀏覽器"
    BINDINGS = [("r", "reload_tree", "重新整理")]

    CSS = """
    Horizontal { height: 1fr; }
    #sidebar { width: 38%; min-width: 28; border-right: solid $primary; }
    #meta { height: 3; padding: 0 1; color: $text-muted; }
    #preview { height: 1fr; padding: 1 2; overflow: auto; }
    """

    def __init__(self, root: Path) -> None:
        super().__init__()
        self.root_path = root.expanduser().resolve(strict=True)
        self.preview_generation = 0

    def compose(self) -> ComposeResult:
        yield Header()
        with Horizontal():
            yield SafeDirectoryTree(self.root_path, id="sidebar")
            with Vertical():
                yield Static(f"根目錄：{self.root_path}", id="meta", markup=False)
                yield Static("請選擇文字檔。", id="preview", markup=False)
        yield Footer()

    def on_directory_tree_directory_selected(
        self,
        event: DirectoryTree.DirectorySelected,
    ) -> None:
        try:
            safe_path = resolve_under_root(event.path, self.root_path)
        except (OSError, PermissionError) as error:
            self.query_one("#meta", Static).update(f"拒絕：{error}")
            return
        self.query_one("#meta", Static).update(f"資料夾：{safe_path}")

    def on_directory_tree_file_selected(
        self,
        event: DirectoryTree.FileSelected,
    ) -> None:
        try:
            safe_path = resolve_under_root(event.path, self.root_path)
        except (OSError, PermissionError) as error:
            self.query_one("#meta", Static).update(f"拒絕：{error}")
            return

        self.preview_generation += 1
        self.query_one("#meta", Static).update(f"檔案：{safe_path}")
        self.load_preview(safe_path, self.preview_generation)

    @work(exclusive=True)
    async def load_preview(self, path: Path, generation: int) -> None:
        try:
            content = await asyncio.to_thread(read_preview, path, self.root_path)
        except (OSError, PermissionError, ValueError) as error:
            content = f"無法預覽：{error}"

        if generation == self.preview_generation:
            self.query_one("#preview", Static).update(content)

    async def action_reload_tree(self) -> None:
        tree = self.query_one("#sidebar", SafeDirectoryTree)
        await tree.reload()
        self.notify("檔案樹已重新整理")


if __name__ == "__main__":
    chosen_root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
    FileBrowser(chosen_root).run()

uv run python browser.py ~/code/my-project

async def action_reload_tree(self) -> None:
    tree = self.query_one("#sidebar", SafeDirectoryTree)
    await tree.reload()

from pathlib import Path

import pytest

from browser import read_preview, resolve_under_root


def test_file_inside_root_is_allowed(tmp_path: Path) -> None:
    note = tmp_path / "note.md"
    note.write_text("hello", encoding="utf-8")
    assert resolve_under_root(note, tmp_path) == note.resolve()


def test_symlink_escape_is_rejected(tmp_path: Path) -> None:
    root = tmp_path / "root"
    outside = tmp_path / "outside"
    root.mkdir()
    outside.mkdir()
    secret = outside / "secret.txt"
    secret.write_text("nope", encoding="utf-8")

    link = root / "escape.txt"
    try:
        link.symlink_to(secret)
    except OSError:
        pytest.skip("此平台不允許建立 symlink")

    with pytest.raises(PermissionError):
        resolve_under_root(link, root)


def test_preview_is_bounded(tmp_path: Path) -> None:
    large = tmp_path / "large.txt"
    large.write_text("x" * (64 * 1024 + 10), encoding="utf-8")
    assert read_preview(large, tmp_path).endswith("… 預覽已截斷 …")

from pathlib import Path

import pytest
from textual.widgets import DirectoryTree, Static

from browser import FileBrowser, SafeDirectoryTree


@pytest.mark.asyncio
async def test_file_selection_updates_preview(tmp_path: Path) -> None:
    note = tmp_path / "note.md"
    note.write_text("拍拍君看到我了", encoding="utf-8")
    app = FileBrowser(tmp_path)

    async with app.run_test() as pilot:
        tree = app.query_one("#sidebar", SafeDirectoryTree)
        tree.post_message(DirectoryTree.FileSelected(tree.root, note))
        await pilot.pause()
        await pilot.pause()

        preview = app.query_one("#preview", Static)
        assert "拍拍君看到我了" in str(preview.content)


@pytest.mark.asyncio
async def test_reload_finishes_cleanly(tmp_path: Path) -> None:
    app = FileBrowser(tmp_path)

    async with app.run_test() as pilot:
        await app.action_reload_tree()
        await pilot.pause()
        assert app.query_one("#sidebar", SafeDirectoryTree).root is not None

uv run pytest -q