flyteplugins-union 0.4.0__tar.gz → 0.4.2__tar.gz

{flyteplugins_union-0.4.0/src/flyteplugins_union.egg-info → flyteplugins_union-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flyteplugins-union
-Version: 0.4.0
+Version: 0.4.2
 Summary: Union SDK - Proprietary extensions for Flyte
 Author-email: unionai <info@union.ai>
 Project-URL: Homepage, https://www.union.ai/

{flyteplugins_union-0.4.0 → flyteplugins_union-0.4.2}/licenses/BSL.txt

@@ -17,7 +17,7 @@ Additional Use Grant: You may make use of the Licensed Work, provided that
                       computer programs whose source code are controlled by
                       such third parties.
 
-Change Date:          2030-06-03
+Change Date:          2030-06-16
 
 Change License:       Apache License, Version 2.0
 

{flyteplugins_union-0.4.0 → flyteplugins_union-0.4.2}/pyproject.toml

@@ -172,6 +172,7 @@ select = [
 # headless installs don't pay the runtime/optional-dep import cost.
 "src/flyteplugins/union/cli/volume.py" = ["PLC0415"]
 "src/flyteplugins/union/cli/_volume_index.py" = ["PLC0415"]
+"src/flyteplugins/union/cli/_volume_session.py" = ["PLC0415"]
 "src/flyteplugins/union/cli/_tui/**/*.py" = ["PLC0415"]
 # VolumeExplore lazy-imports flyte.io / msgpack / boto3 / the Volume model so
 # `import flyteplugins.union.remote` stays light for non-volume callers.

flyteplugins_union-0.4.2/src/flyteplugins/union/cli/_tui/__init__.py

@@ -0,0 +1,36 @@
+"""Lazy entrypoint for the volume explore TUI.
+
+Importing ``textual`` is gated behind the ``[tui]`` extra so headless
+installs don't pay the cost. The launcher below catches the
+:class:`ImportError` and re-raises with a clear install hint, matching the
+ergonomic of :mod:`flyte.cli._tui` upstream.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flyteplugins.union.cli._volume_session import ExploreSession
+
+
+async def launch_volume_explore(*, session: "ExploreSession", title: str, subtitle: str = "") -> None:
+    """Run the volume explore TUI over an :class:`ExploreSession`.
+
+    The session arrives with version 0 already open (reader + summary); the
+    app discovers ancestors in the background and opens their indexes on
+    demand, all without leaving the TUI. The caller owns the session's
+    lifecycle — close it (``session.aclose()``) after this returns.
+
+    Raises a helpful :class:`ImportError` when ``textual`` is not installed.
+    """
+    try:
+        from flyteplugins.union.cli._tui._volume_explore import VolumeExploreApp
+    except ImportError as exc:
+        raise ImportError(
+            "The volume explore TUI requires the 'textual' package. "
+            "Install it with:  pip install 'flyteplugins-union[tui]'"
+        ) from exc
+
+    app = VolumeExploreApp(session=session, title=title, subtitle=subtitle)
+    await app.run_async()

flyteplugins_union-0.4.2/src/flyteplugins/union/cli/_tui/_volume_explore.py

@@ -0,0 +1,595 @@
+"""Textual TUI for browsing a Volume metadata index and its lineage.
+
+Three panes, one long-lived app:
+
+* **Lineage (left)** — the version chain, oldest ancestor at the top, the
+  launched version at the bottom. Ancestors are discovered a couple at a
+  time (each hop is a metadata download, so a deep chain is never walked
+  wholesale): a ``--More--`` row at the top fetches the next batch, and it
+  becomes ``--root--`` once the chain is exhausted. Selecting a version
+  loads its file system *in place* (a worker downloads + opens the index);
+  the screen never tears down. Already-visited versions keep their tree —
+  including expansion state — so hopping back to the child is instant.
+  Below the list, a card shows the highlighted version's metadata
+  (producer, message, stats).
+* **Files (middle)** — the lazy directory tree of the active version, exactly
+  as before (vim ``j``/``k`` + arrows; children fetched on first expand).
+* **File (right)** — metadata about the node under the cursor, nothing else.
+
+Top-level keys: ``q`` quit, ``r`` refresh tree, ``p`` jump to the active
+version's parent (same as selecting it in the lineage pane).
+"""
+
+from __future__ import annotations
+
+import datetime
+import stat as _stat
+from typing import Any, ClassVar, Optional
+
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import ContentSwitcher, Footer, Header, OptionList, Static, Tree
+from textual.widgets.option_list import Option
+from textual.widgets.tree import TreeNode
+
+from flyteplugins.union.cli._volume_index import IndexEntry, IndexReader
+from flyteplugins.union.cli._volume_session import ExploreSession, VersionHandle
+
+# Match flyte-sdk's _explore palette exactly so the experience feels
+# native to anyone who's run `flyte start tui`.
+_FLYTE_PURPLE = "#7652a2"
+_FLYTE_PURPLE_LIGHT = "#f7f5fd"
+_FLYTE_PURPLE_DARK = "#171020"
+
+_KIND_ICON = {
+    "dir": "📁",
+    "file": "📄",
+    "symlink": "🔗",
+}
+
+# Lineage discovery is batched — every hop downloads one metadata object, so
+# the app fetches a couple at a time and parks the rest behind ``--More--``
+# instead of walking a deep (potentially 100-version) chain up front.
+_LINEAGE_BATCH = 2
+_MORE_ID = "lineage-more"
+_ROOT_ID = "lineage-root"
+
+
+def _fmt_size(n: int) -> str:
+    units = ["B", "KB", "MB", "GB", "TB", "PB"]
+    f = float(n)
+    for u in units:
+        if f < 1024 or u == units[-1]:
+            return f"{f:,.1f} {u}" if u != "B" else f"{int(f):,} {u}"
+        f /= 1024
+    return f"{n} B"
+
+
+def _fmt_mtime(mtime_ns: int) -> str:
+    if not mtime_ns:
+        return ""
+    try:
+        dt = datetime.datetime.fromtimestamp(mtime_ns / 1e9)
+    except (OSError, OverflowError, ValueError):
+        return ""
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _fmt_mode(mode: int, kind: str) -> str:
+    if not mode:
+        return f"<{kind}>"
+    try:
+        return _stat.filemode(mode)
+    except (TypeError, ValueError):
+        return oct(mode)
+
+
+def _label(entry: IndexEntry) -> str:
+    icon = _KIND_ICON.get(entry.kind, "•")
+    if entry.kind == "dir":
+        return f"{icon} {entry.name}/"
+    if entry.kind == "symlink" and entry.symlink_target:
+        return f"{icon} {entry.name} → {entry.symlink_target}"
+    return f"{icon} {entry.name}  ({_fmt_size(entry.size)})"
+
+
+class _DetailBox(Static):
+    """Bordered card; markup off so raw paths/JSON render literally."""
+
+    DEFAULT_CSS = """
+    _DetailBox {
+        border: solid $accent;
+        padding: 0 1;
+        margin-bottom: 1;
+        height: auto;
+    }
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("markup", False)
+        super().__init__(*args, **kwargs)
+
+
+class VolumeFileTree(Tree[int]):
+    """Lazy directory tree backed by an :class:`IndexReader`.
+
+    Each node's ``data`` carries the inode number. Directories are added
+    with a stub child so the disclosure arrow shows up; the stub is
+    replaced with real entries on first expand.
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("down,j", "cursor_down", "Cursor Down", show=False),
+        Binding("up,k", "cursor_up", "Cursor Up", show=False),
+    ]
+
+    def __init__(self, reader: IndexReader, root_inode: int, **kwargs: Any) -> None:
+        super().__init__("/", data=root_inode, **kwargs)
+        self.reader = reader
+        self._populated: set[int] = set()
+
+    def on_mount(self) -> None:
+        self.root.allow_expand = True
+        # Reader I/O is async (aiosqlite); populate + expand the root on a
+        # worker so the event loop stays responsive while it loads.
+        self.run_worker(self._populate_and_expand(self.root), exclusive=False)
+
+    def reload(self) -> None:
+        """Reset the tree to its root and re-populate from scratch (the ``r``
+        refresh). Must clear ``_populated`` — otherwise the post-reset root is
+        still flagged as populated and :meth:`_populate` would no-op, leaving an
+        empty tree.
+        """
+        self.reset(self.root.label, data=self.root.data)
+        self._populated.clear()
+        self.root.allow_expand = True
+        self.run_worker(self._populate_and_expand(self.root), exclusive=False)
+
+    async def _populate_and_expand(self, node: TreeNode[int]) -> None:
+        await self._populate(node)
+        node.expand()
+
+    async def _populate(self, node: TreeNode[int]) -> None:
+        inode = node.data
+        if inode is None or inode in self._populated:
+            return
+        self._populated.add(inode)
+        node.remove_children()
+        for entry in await self.reader.children(inode):
+            child = node.add(_label(entry), data=entry.inode, allow_expand=(entry.kind == "dir"))
+            if entry.kind == "dir":
+                # Placeholder so the disclosure arrow shows up; replaced
+                # on first expand.
+                child.add_leaf("…")
+                self._populated.discard(entry.inode)
+
+    def on_tree_node_expanded(self, event: Tree.NodeExpanded) -> None:
+        node = event.node
+        if node.data is not None and node.data not in self._populated:
+            self.run_worker(self._populate(node), exclusive=False)
+
+
+class LineageList(OptionList):
+    """Left-pane version chain, oldest ancestor first (top)."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("down,j", "cursor_down", "Cursor Down", show=False),
+        Binding("up,k", "cursor_up", "Cursor Up", show=False),
+    ]
+
+
+def _version_text(handle: VersionHandle, *, loading: bool = False) -> str:
+    """Render the Version card for one lineage entry."""
+    lines: list[str] = [f"{handle.label}: {handle.name}"]
+    if handle.message:
+        lines.append(f"message: {handle.message}")
+    pb = handle.produced_by or {}
+    if pb:
+        who = pb.get("action") or "?"
+        if pb.get("run"):
+            who = f"{pb['run']} / {who}"
+        lines.append(f"by:      {who}")
+        if pb.get("op"):
+            lines.append(f"output:  {pb['op']}")
+        if pb.get("project") or pb.get("domain"):
+            lines.append(f"scope:   {pb.get('project') or '?'}/{pb.get('domain') or '?'}")
+    # Live summary (once opened) beats the stats stored on the Volume value.
+    inodes = handle.summary.total_inodes if handle.summary is not None else handle.inode_count
+    used = handle.summary.used_bytes if handle.summary is not None else handle.used_bytes
+    if inodes is not None:
+        lines.append(f"inodes:  {inodes:,}")
+    if used is not None:
+        lines.append(f"size:    {_fmt_size(used)} ({used:,} bytes)")
+    if handle.store_type:
+        lines.append(f"backend: {handle.store_type}")
+    if handle.index_path:
+        lines.append(f"index:   {handle.index_path}")
+    if handle.error:
+        lines.append(f"error:   {handle.error}")
+    elif loading:
+        lines.append("state:   loading…")
+    elif handle.opened:
+        lines.append("state:   loaded")
+    else:
+        lines.append("state:   press Enter to load")
+    return "\n".join(lines)
+
+
+def _file_text(entry: IndexEntry, chunk_count: int) -> str:
+    """Render the File card for the node under the tree cursor."""
+    lines: list[str] = []
+    lines.append(f"name:    {entry.name or '/'}")
+    lines.append(f"inode:   {entry.inode}")
+    lines.append(f"kind:    {entry.kind}")
+    if entry.kind == "file":
+        lines.append(f"size:    {_fmt_size(entry.size)} ({entry.size:,} bytes)")
+        if chunk_count >= 0:
+            lines.append(f"chunks:  {chunk_count}")
+        else:
+            lines.append("chunks:  — (not available for this backend)")
+    if entry.kind == "symlink" and entry.symlink_target:
+        lines.append(f"target:  {entry.symlink_target}")
+    lines.append(f"mode:    {_fmt_mode(entry.mode, entry.kind)}  ({oct(entry.mode)})")
+    lines.append(f"owner:   {entry.uid}:{entry.gid}")
+    lines.append(f"nlink:   {entry.nlink}")
+    mtime = _fmt_mtime(entry.mtime_ns)
+    if mtime:
+        lines.append(f"mtime:   {mtime}")
+    return "\n".join(lines)
+
+
+class VolumeExploreApp(App[None]):
+    """Standalone Textual app for browsing a Volume's lineage and indexes."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("q", "quit_app", "Quit"),
+        Binding("r", "refresh_tree", "Refresh"),
+        Binding("p", "open_parent", "Open parent"),
+    ]
+
+    CSS = f"""
+    Screen {{
+        background: {_FLYTE_PURPLE_DARK};
+    }}
+    Header {{
+        background: {_FLYTE_PURPLE};
+        color: {_FLYTE_PURPLE_LIGHT};
+    }}
+    Footer {{
+        background: {_FLYTE_PURPLE};
+        color: {_FLYTE_PURPLE_LIGHT};
+    }}
+    Horizontal {{
+        height: 1fr;
+    }}
+    #lineage-pane {{
+        width: 1fr;
+        min-width: 26;
+    }}
+    LineageList {{
+        height: 1fr;
+        border: solid {_FLYTE_PURPLE};
+        border-title-color: {_FLYTE_PURPLE_LIGHT};
+        background: {_FLYTE_PURPLE_DARK};
+        color: {_FLYTE_PURPLE_LIGHT};
+    }}
+    LineageList > .option-list--option-highlighted {{
+        background: {_FLYTE_PURPLE};
+    }}
+    #tree-switcher {{
+        width: 2fr;
+        min-width: 32;
+        height: 1fr;
+    }}
+    VolumeFileTree {{
+        width: 100%;
+        height: 100%;
+        border: solid {_FLYTE_PURPLE};
+        border-title-color: {_FLYTE_PURPLE_LIGHT};
+        background: {_FLYTE_PURPLE_DARK};
+        color: {_FLYTE_PURPLE_LIGHT};
+    }}
+    #detail-pane {{
+        width: 1fr;
+        min-width: 28;
+        background: {_FLYTE_PURPLE_DARK};
+    }}
+    _DetailBox {{
+        border: solid {_FLYTE_PURPLE};
+        border-title-color: {_FLYTE_PURPLE_LIGHT};
+        padding: 0 1;
+        margin-bottom: 1;
+        height: auto;
+        color: {_FLYTE_PURPLE_LIGHT};
+    }}
+    """
+
+    def __init__(self, *, session: ExploreSession, title: str, subtitle: str = "") -> None:
+        super().__init__()
+        self._session = session
+        self._title = title
+        self._subtitle = subtitle
+        self._active = 0  # index into session.versions of the shown tree
+        self._opening: set[int] = set()  # versions with an in-flight open
+        self._loading_more = False  # a lineage batch fetch is in flight
+
+    # --- layout ---------------------------------------------------------
+
+    def compose(self) -> ComposeResult:
+        first = self._session.versions[0]
+        yield Header()
+        with Horizontal():
+            with Vertical(id="lineage-pane"):
+                lineage = LineageList(id="lineage-list")
+                lineage.border_title = "Lineage  (oldest ↑)"
+                yield lineage
+                yield _DetailBox(id="box-version")
+            with ContentSwitcher(id="tree-switcher", initial="tree-0"):
+                # Version 0's reader is pre-opened by the launcher, so the
+                # first tree mounts synchronously.
+                assert first.reader is not None and first.summary is not None
+                tree = VolumeFileTree(first.reader, root_inode=first.summary.root_inode, id="tree-0")
+                tree.border_title = first.name
+                yield tree
+            with VerticalScroll(id="detail-pane"):
+                yield _DetailBox(id="box-file")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.title = self._title
+        if self._subtitle:
+            self.sub_title = self._subtitle
+        vbox = self.query_one("#box-version", _DetailBox)
+        vbox.border_title = "Version"
+        fbox = self.query_one("#box-file", _DetailBox)
+        fbox.border_title = "File"
+        fbox.update("Pick a file or directory in the tree.")
+        self._rebuild_lineage()
+        self._update_version_card(0)
+        self.query_one("#tree-0", VolumeFileTree).focus()
+        # Discover the first couple of ancestors in the background. Anything
+        # deeper stays behind the ``--More--`` row — each hop is a metadata
+        # download, so a deep chain must never be walked wholesale.
+        self._request_more_lineage()
+
+    # --- lineage pane -----------------------------------------------------
+
+    def _request_more_lineage(self) -> None:
+        """Kick off one bounded batch of ancestor discovery (no-op when a
+        batch is already in flight or the chain is exhausted)."""
+        if self._loading_more or not self._session.has_more():
+            return
+        self._loading_more = True
+        self._rebuild_lineage()
+        self.run_worker(self._load_more_lineage(), exclusive=False, group="lineage")
+
+    async def _load_more_lineage(self) -> None:
+        try:
+            await self._session.extend(_LINEAGE_BATCH)
+        finally:
+            self._loading_more = False
+            self._rebuild_lineage()
+            self.refresh_bindings()
+
+    def _row_prompt(self, idx: int, handle: VersionHandle) -> Text:
+        marker = "●" if idx == self._active else " "
+        text = f"{marker} [{handle.label}] {handle.name}"
+        if handle.message:
+            text += f" — {handle.message}"
+        if handle.error:
+            text += "  (unavailable)"
+        elif idx in self._opening:
+            text += "  (loading…)"
+        return Text(text)
+
+    def _top_marker(self) -> Optional[Option]:
+        """The terminal row above the oldest discovered version.
+
+        ``--More--`` when the chain continues (select it to fetch the next
+        batch), ``--root--`` once the walk has bottomed out. No marker for
+        raw-index sessions (lineage unknowable) or after a failed-load tail
+        (that row is its own terminal indicator).
+        """
+        if self._session.has_more() or self._loading_more:
+            text = "  --More-- (loading…)" if self._loading_more else "  --More--"
+            return Option(Text(text), id=_MORE_ID, disabled=self._loading_more)
+        tip = self._session.versions[-1]
+        if tip.ve is None and (tip.error or len(self._session.versions) == 1):
+            return None
+        return Option(Text("  --root--"), id=_ROOT_ID, disabled=True)
+
+    def _rebuild_lineage(self) -> None:
+        """Re-render the version list (oldest at the top, under the marker
+        row), keeping the highlight on the same row across rebuilds."""
+        lineage = self.query_one("#lineage-list", LineageList)
+        kept: Optional[str] = None
+        if lineage.highlighted is not None:
+            kept = lineage.get_option_at_index(lineage.highlighted).id
+        lineage.clear_options()
+        marker = self._top_marker()
+        if marker is not None:
+            lineage.add_option(marker)
+        lineage.add_options(
+            Option(self._row_prompt(idx, handle), id=str(idx), disabled=bool(handle.error))
+            for idx, handle in reversed(list(enumerate(self._session.versions)))
+        )
+        target = kept if kept is not None else str(self._active)
+        try:
+            lineage.highlighted = lineage.get_option_index(target)
+        except Exception:
+            if target in (_MORE_ID, _ROOT_ID):
+                lineage.highlighted = 0  # the marker was replaced; stay at the top
+            else:
+                lineage.highlighted = lineage.option_count - 1  # bottom = current
+
+    def _update_version_card(self, idx: int) -> None:
+        handle = self._session.versions[idx]
+        self.query_one("#box-version", _DetailBox).update(
+            _version_text(handle, loading=idx in self._opening),
+        )
+
+    def on_option_list_option_highlighted(self, event: OptionList.OptionHighlighted) -> None:
+        if event.option_list.id != "lineage-list" or event.option.id is None:
+            return
+        if event.option.id == _MORE_ID:
+            hint = "Earlier versions exist.\nPress Enter to load a couple more."
+            self.query_one("#box-version", _DetailBox).update(hint)
+            return
+        if event.option.id == _ROOT_ID:
+            self.query_one("#box-version", _DetailBox).update("The lineage ends here — no earlier versions.")
+            return
+        self._update_version_card(int(event.option.id))
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        if event.option_list.id != "lineage-list" or event.option.id is None:
+            return
+        if event.option.id == _MORE_ID:
+            self._request_more_lineage()
+            return
+        if event.option.id == _ROOT_ID:
+            return
+        self._activate(int(event.option.id))
+
+    # --- version switching --------------------------------------------------
+
+    def _activate(self, idx: int) -> None:
+        """Show version ``idx``'s file system, opening its index on demand.
+
+        Everything happens inside the running app: a worker downloads/opens
+        the index while the lineage row shows ``(loading…)``; on success the
+        middle pane switches to that version's tree. Cached versions switch
+        instantly, with their previous expansion state intact.
+        """
+        handle = self._session.versions[idx]
+        if handle.error:
+            self.notify(handle.error, severity="warning")
+            return
+        if idx in self._opening:
+            return
+        self._opening.add(idx)
+        self._rebuild_lineage()
+        self._update_version_card(idx)
+        self.run_worker(self._open_and_switch(idx), exclusive=False, group="open-version")
+
+    async def _open_and_switch(self, idx: int) -> None:
+        try:
+            handle = await self._session.open(idx)
+            if handle.error or handle.reader is None or handle.summary is None:
+                self.notify(
+                    f"Could not open {handle.name}: {handle.error or 'no index'}",
+                    severity="error",
+                    timeout=10,
+                )
+                return
+            switcher = self.query_one("#tree-switcher", ContentSwitcher)
+            if not switcher.query(f"#tree-{idx}"):
+                tree = VolumeFileTree(handle.reader, root_inode=handle.summary.root_inode, id=f"tree-{idx}")
+                tree.border_title = handle.name
+                await switcher.mount(tree)
+            self._switch_to(idx)
+        finally:
+            self._opening.discard(idx)
+            self._rebuild_lineage()
+            self.refresh_bindings()
+
+    def _switch_to(self, idx: int) -> None:
+        handle = self._session.versions[idx]
+        self._active = idx
+        self.query_one("#tree-switcher", ContentSwitcher).current = f"tree-{idx}"
+        # Move the lineage highlight onto the activated version (matters for
+        # ``p``, which switches without touching the list) so the Version card
+        # and the row marker agree on what's shown.
+        lineage = self.query_one("#lineage-list", LineageList)
+        try:
+            lineage.highlighted = lineage.get_option_index(str(idx))
+        except Exception:
+            pass
+        if handle.label != "current":
+            self.sub_title = f"{handle.label}: {handle.name}"
+        else:
+            self.sub_title = self._subtitle or handle.name
+        self._update_version_card(idx)
+        tree = self.query_one(f"#tree-{idx}", VolumeFileTree)
+        tree.focus()
+        # Re-render the File card from this tree's cursor so the right pane
+        # matches the pane in the middle.
+        if tree.cursor_node is not None:
+            self.run_worker(self._render_selected(tree, tree.cursor_node), exclusive=True, group="file-detail")
+        else:
+            self.query_one("#box-file", _DetailBox).update("Pick a file or directory in the tree.")
+
+    # --- file pane ------------------------------------------------------
+
+    def on_tree_node_highlighted(self, event: Tree.NodeHighlighted) -> None:
+        self._maybe_render_selected(event.control, event.node)
+
+    def on_tree_node_selected(self, event: Tree.NodeSelected) -> None:
+        self._maybe_render_selected(event.control, event.node)
+
+    def _maybe_render_selected(self, tree: Tree, node: TreeNode[int]) -> None:
+        # Hidden (cached) trees can still emit highlight events while they
+        # populate; only the active version drives the File card.
+        if tree.id == f"tree-{self._active}":
+            self.run_worker(self._render_selected(tree, node), exclusive=True, group="file-detail")
+
+    async def _render_selected(self, tree: Tree, node: TreeNode[int]) -> None:
+        inode = node.data
+        if inode is None or not isinstance(tree, VolumeFileTree):
+            return
+        entry = await tree.reader.get(inode)
+        if entry is None:
+            return
+        chunks = await tree.reader.chunk_count(inode) if entry.kind == "file" else 0
+        self.query_one("#box-file", _DetailBox).update(_file_text(entry, chunks))
+
+    # --- actions ----------------------------------------------------------
+
+    def check_action(self, action: str, parameters: "tuple[object, ...]") -> "bool | None":
+        """Grey out ``p`` when there is no parent to walk to — discovered or
+        still parked behind ``--More--``."""
+        if action == "open_parent":
+            parent_idx = self._active + 1
+            if parent_idx < len(self._session.versions):
+                return not self._session.versions[parent_idx].error
+            return self._session.has_more()
+        return True
+
+    def action_quit_app(self) -> None:
+        self.exit()
+
+    def action_open_parent(self) -> None:
+        """Jump to the active version's parent — same as selecting it in the
+        lineage pane; the tree swaps in place, no app restart. From the
+        topmost loaded version, fetch the next batch first, then open it."""
+        parent_idx = self._active + 1
+        if parent_idx < len(self._session.versions):
+            self._activate(parent_idx)
+            return
+        if self._session.has_more():
+            self.run_worker(self._load_parent_then_activate(parent_idx), exclusive=False, group="lineage")
+            return
+        self.notify("Already at the root version.", severity="warning")
+
+    async def _load_parent_then_activate(self, parent_idx: int) -> None:
+        """The ``p``-at-the-top path: extend the chain by one batch, then
+        activate the freshly discovered parent."""
+        if self._loading_more:
+            return  # a batch is already in flight; let it land first
+        self._loading_more = True
+        self._rebuild_lineage()
+        try:
+            await self._session.extend(_LINEAGE_BATCH)
+        finally:
+            self._loading_more = False
+            self._rebuild_lineage()
+            self.refresh_bindings()
+        if parent_idx < len(self._session.versions):
+            self._activate(parent_idx)
+
+    def action_refresh_tree(self) -> None:
+        # Re-populate the active tree against the same reader. The reader is
+        # snapshot-based (already-downloaded index), so this is purely a state
+        # reset — useful after an accidental collapse-all.
+        self.query_one(f"#tree-{self._active}", VolumeFileTree).reload()