Refactor TUI from screen-pushing to panel-swapping navigation model

Replace pushed Screens (ProjectListScreen, ModuleListScreen,
FeatureListScreen) with Widget-based panels that mount inside
#main-content, keeping chrome (K9sHeader, CommandBar, StatusBar)
always visible. Move navigation bindings and logic into MFBTApp,
integrate breadcrumb into K9sHeader, fix token manager to preserve
existing auth fields on refresh, and update tests accordingly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shuveb

src/mfbt/token_manager.py

@@ -95,17 +95,18 @@ def __init__(
         self.base_url = base_url
 
     def save_tokens(self, token_response: TokenResponse) -> None:
-        """Save tokens to auth.json, adding issued_at timestamp."""
-        from mfbt.config import save_auth
-
-        auth_data: dict[str, Any] = {
-            "access_token": token_response.access_token,
-            "refresh_token": token_response.refresh_token,
-            "token_type": token_response.token_type,
-            "expires_at": token_response.expires_at,
-            "issued_at": token_response.issued_at
-            or datetime.now(timezone.utc).isoformat(),
-        }
+        """Save tokens to auth.json, preserving existing fields like client_id."""
+        from mfbt.config import load_auth, save_auth
+
+        # Load existing auth to preserve client_id and other fields
+        auth_data = load_auth(self.project_root)
+        auth_data["access_token"] = token_response.access_token
+        auth_data["refresh_token"] = token_response.refresh_token
+        auth_data["token_type"] = token_response.token_type
+        auth_data["expires_at"] = token_response.expires_at
+        auth_data["issued_at"] = (
+            token_response.issued_at or datetime.now(timezone.utc).isoformat()
+        )
         save_auth(self.project_root, auth_data)
         logger.info("Tokens saved via TokenManager")
 
@@ -409,7 +410,11 @@ def _run(self) -> None:
             except TokenRefreshNetworkError:
                 # Transient — log and keep monitoring
                 logger.warning("Token refresh transient failure, will retry next cycle")
+                if self._on_refreshed is not None:
+                    self._on_refreshed()
             except Exception:
                 logger.exception("Unexpected error in token monitor")
+                if self._on_refreshed is not None:
+                    self._on_refreshed()
 
             self._stop_event.wait(timeout=self._check_interval)

src/mfbt/tui/app.py

@@ -1,4 +1,10 @@
-"""Main Textual application for the mfbt TUI."""
+"""Main Textual application for the mfbt TUI.
+
+Uses a panel-swapping model: the chrome (K9sHeader, CommandBar,
+StatusBar) stays mounted at all times. Content panels (project list, module
+list, feature list) are swapped inside #main-content. Modal overlays (feature
+detail, info modal, help) are pushed as ModalScreen on top.
+"""
 
 from __future__ import annotations
 
@@ -11,7 +17,6 @@
 
 from mfbt.tui.data_provider import TUIDataProvider
 from mfbt.tui.navigation import NavigationItem, NavigationLevel, NavigationState
-from mfbt.tui.widgets.breadcrumb_bar import BreadcrumbBar
 from mfbt.tui.widgets.command_bar import CommandBar
 from mfbt.tui.widgets.k9s_header import K9sHeader
 from mfbt.tui.widgets.status_bar import StatusBar
@@ -59,6 +64,10 @@ class MFBTApp(App):
     BINDINGS = [
         Binding("q", "quit", "Quit", priority=True),
         Binding("question_mark", "show_help", "Help", show=False),
+        Binding("escape", "go_back", "Back", show=False),
+        Binding("backspace", "go_back", "Back", show=False),
+        Binding("r", "refresh", "Refresh", show=False),
+        Binding("d", "describe", "Describe", show=False),
     ]
 
     def __init__(
@@ -79,15 +88,12 @@ def __init__(
 
     def compose(self) -> ComposeResult:
         yield K9sHeader(id="k9s-header")
-        yield BreadcrumbBar(id="breadcrumb-bar")
         yield Container(id="main-content")
         yield CommandBar(id="command-bar")
         yield StatusBar(id="status-bar")
 
     def on_mount(self) -> None:
-        from mfbt.tui.screens.project_list import ProjectListScreen
-
-        self.push_screen(ProjectListScreen(self.data_provider))
+        self._show_project_list()
         self._update_nav_display()
 
         # Wire up transport change callback
@@ -104,6 +110,227 @@ def _on_transport(mode: TransportMode) -> None:
         # Start background token monitor
         self._start_token_monitor()
 
+    # ---- Content panel swapping ----------------------------------------
+
+    def _clear_main_content(self) -> None:
+        """Remove all children from #main-content."""
+        container = self.query_one("#main-content", Container)
+        container.remove_children()
+
+    def _show_project_list(self) -> None:
+        """Mount the project list panel."""
+        from mfbt.tui.screens.project_list import ProjectListPanel
+
+        self._clear_main_content()
+        container = self.query_one("#main-content", Container)
+        container.mount(ProjectListPanel(self.data_provider))
+
+    def _show_module_list(
+        self,
+        project_id: str,
+        project_name: str,
+        project_key: str,
+        project_metadata: dict[str, Any],
+    ) -> None:
+        """Mount the module list panel for a project."""
+        from mfbt.tui.screens.module_list import ModuleListPanel
+
+        self._clear_main_content()
+        container = self.query_one("#main-content", Container)
+        container.mount(
+            ModuleListPanel(
+                data_provider=self.data_provider,
+                project_id=project_id,
+                project_name=project_name,
+                project_key=project_key,
+                project_metadata=project_metadata,
+            )
+        )
+
+    def _show_feature_list(
+        self,
+        project_id: str,
+        project_name: str,
+        project_key: str,
+        project_metadata: dict[str, Any],
+        module_id: str,
+        module_name: str,
+        module_key: str,
+        module_metadata: dict[str, Any],
+    ) -> None:
+        """Mount the feature list panel for a module."""
+        from mfbt.tui.screens.feature_list import FeatureListPanel
+
+        self._clear_main_content()
+        container = self.query_one("#main-content", Container)
+        container.mount(
+            FeatureListPanel(
+                data_provider=self.data_provider,
+                project_id=project_id,
+                project_name=project_name,
+                module_id=module_id,
+                module_name=module_name,
+                module_key=module_key,
+                module_metadata=module_metadata,
+            )
+        )
+
+    # ---- Message handlers from content panels --------------------------
+
+    def on_project_list_panel_project_selected(
+        self, event: Any
+    ) -> None:
+        """Handle project selection: navigate to modules."""
+        data = event.data
+        project_id = data.get("id", "")
+        project_name = data.get("name", "Unknown")
+        project_key = data.get("key", data.get("short_url_id", ""))
+        tech_stack = data.get("tech_stack", "")
+        if isinstance(tech_stack, list):
+            tech_stack = ", ".join(tech_stack[:3])
+
+        project_metadata = {
+            "tech_stack": tech_stack,
+            "status": data.get("status", ""),
+            "description": data.get("description", ""),
+        }
+
+        # Push nav state
+        self.nav_state.drill_down(
+            NavigationItem(
+                id=project_id,
+                name=project_name,
+                level=NavigationLevel.PROJECTS,
+                key=project_key,
+                metadata=project_metadata,
+            )
+        )
+
+        self._show_module_list(project_id, project_name, project_key, project_metadata)
+        self._update_nav_display()
+
+    def on_module_list_panel_module_selected(
+        self, event: Any
+    ) -> None:
+        """Handle module selection: navigate to features."""
+        data = event.data
+        module_id = data.get("id", "")
+        module_name = data.get("title", data.get("name", "Unknown"))
+        module_key = data.get("module_key", data.get("key", ""))
+        feature_count = data.get("feature_count", 0)
+
+        module_metadata = {
+            "feature_count": feature_count or 0,
+        }
+
+        # The project info is carried in the event
+        project_id = event.project_id
+        project_name = event.project_name
+        project_key = event.project_key
+        project_metadata = event.project_metadata
+
+        # Push nav state
+        self.nav_state.drill_down(
+            NavigationItem(
+                id=module_id,
+                name=module_name,
+                level=NavigationLevel.MODULES,
+                key=module_key,
+                metadata=module_metadata,
+            )
+        )
+
+        self._show_feature_list(
+            project_id=project_id,
+            project_name=project_name,
+            project_key=project_key,
+            project_metadata=project_metadata,
+            module_id=module_id,
+            module_name=module_name,
+            module_key=module_key,
+            module_metadata=module_metadata,
+        )
+        self._update_nav_display()
+
+    def on_feature_list_panel_feature_selected(
+        self, event: Any
+    ) -> None:
+        """Handle feature selection: open detail modal."""
+        from mfbt.tui.screens.feature_detail import FeatureDetailScreen
+
+        feature_id = event.data.get("id", "")
+        self.push_screen(
+            FeatureDetailScreen(
+                data_provider=self.data_provider,
+                feature_id=feature_id,
+                feature_data=event.data,
+            )
+        )
+
+    # ---- Describe handlers from content panels -------------------------
+
+    def _handle_describe(self, data: dict[str, Any] | None, resource_type: str) -> None:
+        """Open info modal for the given resource."""
+        if data:
+            from mfbt.tui.screens.info_modal import InfoModal
+
+            self.push_screen(InfoModal(data=data, resource_type=resource_type))
+
+    # ---- Navigation actions -------------------------------------------
+
+    def action_go_back(self) -> None:
+        """Navigate back one level."""
+        level = self.nav_state.level
+        if level == NavigationLevel.PROJECTS:
+            return  # Already at root, do nothing
+        elif level == NavigationLevel.MODULES:
+            self.nav_state.go_up()
+            self._show_project_list()
+        elif level == NavigationLevel.FEATURES:
+            self.nav_state.go_up()
+            # Restore module list
+            if self.nav_state.stack:
+                proj = self.nav_state.stack[0]
+                self._show_module_list(
+                    project_id=proj.id,
+                    project_name=proj.name,
+                    project_key=proj.key,
+                    project_metadata=proj.metadata,
+                )
+        self._update_nav_display()
+
+    def action_refresh(self) -> None:
+        """Refresh the current content panel."""
+        from mfbt.tui.screens.feature_list import FeatureListPanel
+        from mfbt.tui.screens.module_list import ModuleListPanel
+        from mfbt.tui.screens.project_list import ProjectListPanel
+
+        container = self.query_one("#main-content", Container)
+        for child in container.children:
+            if isinstance(child, (ProjectListPanel, ModuleListPanel, FeatureListPanel)):
+                child.refresh_data()
+                break
+
+    def action_describe(self) -> None:
+        """Show info modal for the selected item."""
+        from mfbt.tui.screens.feature_list import FeatureListPanel
+        from mfbt.tui.screens.module_list import ModuleListPanel
+        from mfbt.tui.screens.project_list import ProjectListPanel
+
+        container = self.query_one("#main-content", Container)
+        for child in container.children:
+            if isinstance(child, ProjectListPanel):
+                self._handle_describe(child.get_selected_data(), "project")
+                return
+            if isinstance(child, ModuleListPanel):
+                self._handle_describe(child.get_selected_data(), "module")
+                return
+            if isinstance(child, FeatureListPanel):
+                self._handle_describe(child.get_selected_data(), "feature")
+                return
+
+    # ---- Token monitor -------------------------------------------------
+
     def _start_token_monitor(self) -> None:
         """Start the background token refresh monitor."""
         from mfbt.token_manager import BackgroundTokenMonitor
@@ -150,8 +377,7 @@ def _update_transport(self, mode: TransportMode) -> None:
         except Exception:
             pass
 
-    def on_screen_resume(self) -> None:
-        self._update_nav_display()
+    # ---- Display updates -----------------------------------------------
 
     def on_resize(self) -> None:
         if self.size.width < 80:
@@ -171,13 +397,6 @@ def action_show_help(self) -> None:
 
     def _update_nav_display(self) -> None:
         """Update breadcrumb, header, command bar, and status bar from nav state."""
-        # Breadcrumb bar
-        try:
-            breadcrumb = self.query_one("#breadcrumb-bar", BreadcrumbBar)
-            breadcrumb.path_rich = self.nav_state.breadcrumb_path_rich
-        except Exception:
-            pass
-
         # Command bar hints
         try:
             command_bar = self.query_one("#command-bar", CommandBar)
@@ -191,6 +410,7 @@ def _update_nav_display(self) -> None:
         # K9s header context
         try:
             header = self.query_one("#k9s-header", K9sHeader)
+            header.breadcrumb = self.nav_state.breadcrumb_path_rich
             level = self.nav_state.level
             header.context_level = level.value
 
@@ -227,43 +447,3 @@ def _update_nav_display(self) -> None:
                 status_bar.resource_type = "Features"
         except Exception:
             pass
-
-    def push_screen(  # type: ignore[override]
-        self, screen: Any, *args: Any, **kwargs: Any
-    ) -> Any:
-        """Override to track navigation state on screen push."""
-        # Track navigation for non-modal screens
-        from mfbt.tui.screens.feature_list import FeatureListScreen
-        from mfbt.tui.screens.module_list import ModuleListScreen
-
-        if isinstance(screen, ModuleListScreen):
-            self.nav_state.drill_down(
-                NavigationItem(
-                    id=screen.project_id,
-                    name=screen.project_name,
-                    level=NavigationLevel.PROJECTS,
-                    key=getattr(screen, "project_key", ""),
-                    metadata=getattr(screen, "project_metadata", {}),
-                )
-            )
-        elif isinstance(screen, FeatureListScreen):
-            self.nav_state.drill_down(
-                NavigationItem(
-                    id=screen.module_id,
-                    name=screen.module_name,
-                    level=NavigationLevel.MODULES,
-                    key=getattr(screen, "module_key", ""),
-                    metadata=getattr(screen, "module_metadata", {}),
-                )
-            )
-
-        result = super().push_screen(screen, *args, **kwargs)
-        self._update_nav_display()
-        return result
-
-    def pop_screen(self) -> Any:
-        """Override to track navigation state on screen pop."""
-        self.nav_state.go_up()
-        result = super().pop_screen()
-        self._update_nav_display()
-        return result