clue2app-cli 0.2.7__py3-none-any.whl

clue2app_cli/tui/textual_app.py

@@ -0,0 +1,1021 @@
+"""Textual-based TUI for Clue2App CLI.
+
+Provides a k9s-like interactive terminal interface using the Textual framework.
+"""
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal, Vertical
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, Static, Label, Button
+from textual.reactive import reactive
+from textual import work
+from textual.worker import Worker, get_current_worker
+
+from typing import Optional, List
+from rich.text import Text
+
+from .data import DataProvider, AppInfo, ProjectInfo, AppStatus, BuildStatus
+
+
+class AppRow:
+    """Helper to format app data for table display."""
+
+    @staticmethod
+    def build_status_text(status: BuildStatus) -> Text:
+        """Format build status with color."""
+        colors = {
+            BuildStatus.READY: "green",
+            BuildStatus.BUILDING: "yellow",
+            BuildStatus.FAILED: "red",
+            BuildStatus.UNKNOWN: "dim",
+        }
+        symbol = {
+            BuildStatus.READY: "✓",
+            BuildStatus.BUILDING: "⟳",
+            BuildStatus.FAILED: "✗",
+            BuildStatus.UNKNOWN: "?",
+        }
+        return Text(f"{symbol[status]} {status.value}", style=colors[status])
+
+    @staticmethod
+    def runtime_status_text(status: AppStatus, pods: int) -> Text:
+        """Format runtime status with color."""
+        colors = {
+            AppStatus.RUNNING: "green",
+            AppStatus.SCALED_TO_ZERO: "yellow",
+            AppStatus.STOPPED: "red",
+            AppStatus.BUILDING: "cyan",
+            AppStatus.FAILED: "red",
+            AppStatus.UNKNOWN: "dim",
+        }
+        return Text(f"{status.value} ({pods})", style=colors[status])
+
+
+class StatusBar(Static):
+    """Bottom status bar showing context and help."""
+
+    project_name: reactive[str] = reactive("")
+
+    def render(self) -> Text:
+        project = f"Project: {self.project_name}" if self.project_name else "No project selected"
+        return Text.from_markup(f"[bold cyan]{project}[/] | Press [bold]?[/] for help")
+
+
+class CommandBar(Static):
+    """k9s-style command bar showing available shortcuts."""
+
+    DEFAULT_CSS = """
+    CommandBar {
+        dock: top;
+        height: 1;
+        background: $surface-darken-1;
+        padding: 0 1;
+    }
+    """
+
+    commands: reactive[str] = reactive("")
+
+    def render(self) -> Text:
+        return Text.from_markup(self.commands)
+
+    @staticmethod
+    def format_commands(commands: list[tuple[str, str]]) -> str:
+        """Format commands as k9s-style bar.
+
+        Args:
+            commands: List of (key, description) tuples
+        """
+        parts = []
+        for key, desc in commands:
+            parts.append(f"[bold cyan]<{key}>[/] {desc}")
+        return " | ".join(parts)
+
+
+class AppsScreen(Screen):
+    """Main apps list screen."""
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("escape", "noop", "Home", priority=True, show=False),  # Prevent escape from closing app
+        Binding("?", "help", "Help"),
+        Binding("enter", "select", "Details"),
+        Binding("l", "logs", "Logs"),
+        Binding("r", "rebuild", "Rebuild"),
+        Binding("d", "delete", "Delete"),
+        Binding("p", "projects", "Projects"),
+        Binding("R", "refresh", "Refresh"),
+        Binding("u", "toggle_unlinked", "Unlinked"),
+        Binding("a", "toggle_all", "All Projects"),
+    ]
+
+    show_unlinked: reactive[bool] = reactive(False)
+    show_all: reactive[bool] = reactive(False)  # False = show only current project
+    apps: reactive[List[AppInfo]] = reactive([])
+
+    def __init__(self, data_provider: DataProvider, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.data_provider = data_provider
+        self._selected_app: Optional[AppInfo] = None
+        self._current_project: Optional[ProjectInfo] = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield CommandBar(id="command-bar")
+        yield Container(
+            Static("Loading apps...", id="loading"),
+            DataTable(id="apps-table"),
+            id="main-container"
+        )
+        yield StatusBar(id="status-bar")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Set up the table and load data."""
+        # Get current project context
+        self._current_project = self.data_provider.get_current_project()
+
+        # Set up command bar
+        self._update_command_bar()
+
+        table = self.query_one("#apps-table", DataTable)
+        table.cursor_type = "row"
+        table.zebra_stripes = True
+
+        # Add columns
+        table.add_column("Name", key="name", width=30)
+        table.add_column("Project", key="project", width=20)
+        table.add_column("Build", key="build", width=15)
+        table.add_column("Runtime", key="runtime", width=20)
+        table.add_column("URL", key="url", width=40)
+
+        # Update status bar with current project
+        status_bar = self.query_one("#status-bar", StatusBar)
+        status_bar.project_name = self._current_project.name if self._current_project else ""
+
+        # Load apps
+        self.load_apps()
+
+    def _update_command_bar(self) -> None:
+        """Update command bar based on current state."""
+        cmd_bar = self.query_one("#command-bar", CommandBar)
+        commands = [
+            ("Enter", "Details"),
+            ("l", "Logs"),
+            ("r", "Rebuild"),
+            ("d", "Delete"),
+            ("p", "Projects"),
+        ]
+        # Show "a" toggle only if a project is selected
+        if self._current_project:
+            scope = "All" if self.show_all else self._current_project.name
+            commands.append(("a", f"Scope:{scope}"))
+        commands.extend([
+            ("u", "Unlinked"),
+            ("?", "Help"),
+            ("q", "Quit"),
+        ])
+        cmd_bar.commands = CommandBar.format_commands(commands)
+
+    @work(exclusive=True)
+    async def load_apps(self) -> None:
+        """Load apps in background."""
+        worker = get_current_worker()
+
+        try:
+            # Determine project filter
+            project_id = None
+            if self._current_project and not self.show_all:
+                project_id = self._current_project.id
+
+            apps = self.data_provider.get_apps(
+                project_id=project_id,
+                include_unlinked=self.show_unlinked
+            )
+
+            if not worker.is_cancelled:
+                self.call_from_thread(self._update_table, apps)
+        except Exception as e:
+            if not worker.is_cancelled:
+                self.call_from_thread(self._show_error, str(e))
+
+    def _update_table(self, apps: List[AppInfo]) -> None:
+        """Update the table with app data."""
+        self.apps = apps
+
+        # Hide loading indicator
+        loading = self.query_one("#loading", Static)
+
+        # Update table
+        table = self.query_one("#apps-table", DataTable)
+        table.clear()
+
+        # Show helpful message if no apps found with project filter
+        if not apps and self._current_project and not self.show_all:
+            loading.update(
+                f"[yellow]No apps linked to project '{self._current_project.name}'[/yellow]\n\n"
+                "[dim]Press [bold]a[/bold] to show all apps, or [bold]u[/bold] to show unlinked apps.\n"
+                "Use [bold]c2a apps link <app> --project-id <id>[/bold] to link apps to this project.[/dim]"
+            )
+            loading.display = True
+            table.display = False
+            return
+
+        loading.display = False
+        table.display = True
+
+        for app in apps:
+            project_text = Text(app.project_name or "(unlinked)", style="yellow" if not app.project_name else "green")
+            url_text = Text(app.url or "-", style="cyan" if app.url else "dim")
+
+            table.add_row(
+                app.display_name,
+                project_text,
+                AppRow.build_status_text(app.build_status),
+                AppRow.runtime_status_text(app.runtime_status, app.pod_count),
+                url_text,
+                key=app.name
+            )
+
+    def _show_error(self, message: str) -> None:
+        """Show error message."""
+        loading = self.query_one("#loading", Static)
+        loading.update(f"[red]Error: {message}[/red]")
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        """Handle row selection."""
+        if event.row_key:
+            app_name = str(event.row_key.value)
+            for app in self.apps:
+                if app.name == app_name:
+                    self._selected_app = app
+                    break
+
+    def action_refresh(self) -> None:
+        """Refresh the apps list."""
+        loading = self.query_one("#loading", Static)
+        loading.update("Refreshing...")
+        loading.display = True
+        self.load_apps()
+
+    def action_toggle_unlinked(self) -> None:
+        """Toggle showing unlinked apps."""
+        self.show_unlinked = not self.show_unlinked
+        self.action_refresh()
+
+    def action_toggle_all(self) -> None:
+        """Toggle showing all projects vs current project only."""
+        if not self._current_project:
+            self.notify("No project selected - showing all apps", severity="warning")
+            return
+        self.show_all = not self.show_all
+        self._update_command_bar()
+        self.action_refresh()
+
+    def action_noop(self) -> None:
+        """Do nothing - prevents escape from closing app on home screen."""
+        pass
+
+    def action_logs(self) -> None:
+        """View logs for selected app."""
+        table = self.query_one("#apps-table", DataTable)
+        if table.cursor_row is not None and self.apps:
+            row_key = table.get_row_at(table.cursor_row)
+            # Find the app
+            for app in self.apps:
+                if app.name == str(table.get_row_key_at(table.cursor_row).value):
+                    self.app.push_screen(LogsScreen(self.data_provider, app))
+                    break
+
+    def action_rebuild(self) -> None:
+        """Rebuild selected app."""
+        table = self.query_one("#apps-table", DataTable)
+        if table.cursor_row is not None and self.apps:
+            for app in self.apps:
+                if app.name == str(table.get_row_key_at(table.cursor_row).value):
+                    self.app.push_screen(ConfirmScreen(
+                        f"Rebuild '{app.display_name}'?",
+                        lambda: self._do_rebuild(app)
+                    ))
+                    break
+
+    def _do_rebuild(self, app: AppInfo) -> None:
+        """Execute rebuild."""
+        result = self.data_provider.rebuild_app(app.name)
+        if result:
+            self.notify(f"Rebuild triggered for {app.display_name}")
+        else:
+            self.notify(f"Failed to rebuild {app.display_name}", severity="error")
+        self.action_refresh()
+
+    def action_delete(self) -> None:
+        """Delete selected app."""
+        table = self.query_one("#apps-table", DataTable)
+        if table.cursor_row is not None and self.apps:
+            for app in self.apps:
+                if app.name == str(table.get_row_key_at(table.cursor_row).value):
+                    self.app.push_screen(ConfirmScreen(
+                        f"Delete '{app.display_name}'? This cannot be undone!",
+                        lambda: self._do_delete(app)
+                    ))
+                    break
+
+    def _do_delete(self, app: AppInfo) -> None:
+        """Execute delete."""
+        if self.data_provider.delete_app(app.name):
+            self.notify(f"Deleted {app.display_name}")
+        else:
+            self.notify(f"Failed to delete {app.display_name}", severity="error")
+        self.action_refresh()
+
+    def action_select(self) -> None:
+        """Show details for selected app."""
+        table = self.query_one("#apps-table", DataTable)
+        if table.cursor_row is not None and self.apps:
+            for app in self.apps:
+                if app.name == str(table.get_row_key_at(table.cursor_row).value):
+                    self.app.push_screen(DetailsScreen(self.data_provider, app))
+                    break
+
+    def action_projects(self) -> None:
+        """Switch to projects screen."""
+        self.app.push_screen(ProjectsScreen(self.data_provider))
+
+    def action_help(self) -> None:
+        """Show help screen."""
+        self.app.push_screen(HelpScreen())
+
+
+class LogsScreen(Screen):
+    """Log viewer screen."""
+
+    BINDINGS = [
+        Binding("q", "back", "Back"),
+        Binding("escape", "back", "Back", priority=True),
+        Binding("f", "toggle_follow", "Follow"),
+        Binding("g", "scroll_top", "Top"),
+        Binding("G", "scroll_bottom", "Bottom"),
+        Binding("b", "toggle_log_type", "Build/Instance"),
+        Binding("R", "refresh_logs", "Refresh"),
+        # vi-style navigation
+        Binding("j", "scroll_down", "Down", show=False),
+        Binding("k", "scroll_up", "Up", show=False),
+        Binding("ctrl+d", "page_down", "Page Down", show=False),
+        Binding("ctrl+u", "page_up", "Page Up", show=False),
+        Binding("ctrl+f", "page_down", "Page Down", show=False),
+        Binding("ctrl+b", "page_up", "Page Up", show=False),
+        Binding("/", "search", "Search"),
+        Binding("n", "search_next", "Next", show=False),
+        Binding("N", "search_prev", "Prev", show=False),
+    ]
+
+    following: reactive[bool] = reactive(False)
+    log_type: reactive[str] = reactive("auto")  # "auto", "instance", "build"
+    search_term: reactive[str] = reactive("")
+    search_matches: reactive[List[int]] = reactive([])
+    current_match: reactive[int] = reactive(-1)
+
+    def __init__(self, data_provider: DataProvider, app: AppInfo, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.data_provider = data_provider
+        self.app_info = app
+        self._log_worker: Optional[Worker] = None
+        self._log_lines: List[str] = []
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield CommandBar(id="command-bar")
+        yield Container(
+            Static(f"[bold]Logs: {self.app_info.display_name}[/bold]", id="logs-header"),
+            Static("Loading logs...", id="logs-content"),
+            id="logs-container"
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Load initial logs."""
+        self._update_command_bar()
+        self.load_logs()
+
+    def _update_command_bar(self) -> None:
+        """Update command bar based on current state."""
+        cmd_bar = self.query_one("#command-bar", CommandBar)
+        log_type_label = {"auto": "Auto", "instance": "Instance", "build": "Build"}[self.log_type]
+        cmd_bar.commands = CommandBar.format_commands([
+            ("b", f"Type:{log_type_label}"),
+            ("j/k", "Up/Down"),
+            ("/", "Search"),
+            ("R", "Refresh"),
+            ("g/G", "Top/Bottom"),
+            ("Esc", "Back"),
+        ])
+
+    def _update_header(self) -> None:
+        """Update header with current log type."""
+        header = self.query_one("#logs-header", Static)
+        log_type_label = {"auto": "", "instance": " [cyan][Instance][/cyan]", "build": " [yellow][Build][/yellow]"}[self.log_type]
+        follow_label = " [green][Following][/green]" if self.following else ""
+        header.update(f"[bold]Logs: {self.app_info.display_name}[/bold]{log_type_label}{follow_label}")
+
+    @work(exclusive=True)
+    async def load_logs(self) -> None:
+        """Load logs in background."""
+        worker = get_current_worker()
+        try:
+            logs = self.data_provider.get_logs(self.app_info.name, lines=200, log_type=self.log_type)
+            if not worker.is_cancelled:
+                self.call_from_thread(self._update_logs, logs)
+        except Exception as e:
+            if not worker.is_cancelled:
+                self.call_from_thread(self._show_error, str(e))
+
+    def _update_logs(self, logs: str) -> None:
+        """Update logs display."""
+        self._log_lines = logs.split('\n') if logs else []
+        content = self.query_one("#logs-content", Static)
+        content.update(logs if logs else "[dim]No logs available[/dim]")
+
+    def _show_error(self, message: str) -> None:
+        """Show error message."""
+        content = self.query_one("#logs-content", Static)
+        content.update(f"[red]Error: {message}[/red]")
+
+    def action_back(self) -> None:
+        """Go back to apps screen."""
+        self.app.pop_screen()
+
+    def action_toggle_follow(self) -> None:
+        """Toggle log following."""
+        self.following = not self.following
+        self._update_header()
+
+    def action_toggle_log_type(self) -> None:
+        """Toggle between log types (auto -> instance -> build -> auto)."""
+        if self.log_type == "auto":
+            self.log_type = "instance"
+        elif self.log_type == "instance":
+            self.log_type = "build"
+        else:
+            self.log_type = "auto"
+        self._update_command_bar()
+        self._update_header()
+        self.load_logs()
+
+    def action_refresh_logs(self) -> None:
+        """Refresh logs."""
+        content = self.query_one("#logs-content", Static)
+        content.update("Refreshing logs...")
+        self.load_logs()
+
+    def action_scroll_top(self) -> None:
+        """Scroll to top."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_home()
+
+    def action_scroll_bottom(self) -> None:
+        """Scroll to bottom."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_end()
+
+    def action_scroll_down(self) -> None:
+        """Scroll down one line (vi j)."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_relative(y=1)
+
+    def action_scroll_up(self) -> None:
+        """Scroll up one line (vi k)."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_relative(y=-1)
+
+    def action_page_down(self) -> None:
+        """Scroll down half page (vi Ctrl-d)."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_relative(y=container.size.height // 2)
+
+    def action_page_up(self) -> None:
+        """Scroll up half page (vi Ctrl-u)."""
+        container = self.query_one("#logs-container", Container)
+        container.scroll_relative(y=-(container.size.height // 2))
+
+    def action_search(self) -> None:
+        """Start search (vi /)."""
+        self.app.push_screen(SearchScreen(self._do_search))
+
+    def _do_search(self, term: str) -> None:
+        """Execute search."""
+        if not term:
+            return
+        self.search_term = term
+        self.search_matches = []
+        self.current_match = -1
+
+        # Find all matching lines
+        for i, line in enumerate(self._log_lines):
+            if term.lower() in line.lower():
+                self.search_matches.append(i)
+
+        if self.search_matches:
+            self.current_match = 0
+            self._highlight_match()
+            self.notify(f"Found {len(self.search_matches)} matches")
+        else:
+            self.notify(f"No matches for '{term}'", severity="warning")
+
+    def _highlight_match(self) -> None:
+        """Highlight current match and scroll to it."""
+        if self.current_match < 0 or self.current_match >= len(self.search_matches):
+            return
+
+        # Re-render logs with highlighting
+        content = self.query_one("#logs-content", Static)
+        highlighted_lines = []
+        for i, line in enumerate(self._log_lines):
+            if i == self.search_matches[self.current_match]:
+                highlighted_lines.append(f"[reverse]{line}[/reverse]")
+            elif self.search_term.lower() in line.lower():
+                # Highlight search term in other matches
+                highlighted_lines.append(line.replace(
+                    self.search_term,
+                    f"[bold yellow]{self.search_term}[/bold yellow]"
+                ))
+            else:
+                highlighted_lines.append(line)
+        content.update('\n'.join(highlighted_lines))
+
+        # Scroll to match
+        container = self.query_one("#logs-container", Container)
+        match_line = self.search_matches[self.current_match]
+        container.scroll_to(y=match_line)
+
+    def action_search_next(self) -> None:
+        """Go to next search match (vi n)."""
+        if not self.search_matches:
+            return
+        self.current_match = (self.current_match + 1) % len(self.search_matches)
+        self._highlight_match()
+
+    def action_search_prev(self) -> None:
+        """Go to previous search match (vi N)."""
+        if not self.search_matches:
+            return
+        self.current_match = (self.current_match - 1) % len(self.search_matches)
+        self._highlight_match()
+
+
+class SearchScreen(Screen):
+    """Search input dialog."""
+
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel", priority=True),
+    ]
+
+    def __init__(self, on_search: callable, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.on_search = on_search
+
+    def compose(self) -> ComposeResult:
+        from textual.widgets import Input
+        yield Container(
+            Static("[bold]Search:[/bold]", id="search-label"),
+            Input(placeholder="Enter search term...", id="search-input"),
+            id="search-dialog"
+        )
+
+    def on_mount(self) -> None:
+        """Focus the input."""
+        self.query_one("#search-input").focus()
+
+    def on_input_submitted(self, event) -> None:
+        """Handle search submission."""
+        term = event.value
+        self.app.pop_screen()
+        self.on_search(term)
+
+    def action_cancel(self) -> None:
+        """Cancel search."""
+        self.app.pop_screen()
+
+
+class DetailsScreen(Screen):
+    """App details screen."""
+
+    BINDINGS = [
+        Binding("q", "back", "Back"),
+        Binding("escape", "back", "Back", priority=True),
+        Binding("l", "logs", "Logs"),
+        Binding("r", "rebuild", "Rebuild"),
+        Binding("o", "open_url", "Open URL"),
+    ]
+
+    def __init__(self, data_provider: DataProvider, app: AppInfo, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.data_provider = data_provider
+        self.app_info = app
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield CommandBar(id="command-bar")
+        yield Container(
+            Static(self._render_details(), id="details-content"),
+            id="details-container"
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Set up command bar."""
+        cmd_bar = self.query_one("#command-bar", CommandBar)
+        cmd_bar.commands = CommandBar.format_commands([
+            ("l", "Logs"),
+            ("r", "Rebuild"),
+            ("o", "Open URL"),
+            ("Esc", "Back"),
+        ])
+
+    def _render_details(self) -> str:
+        """Render app details."""
+        app = self.app_info
+        lines = [
+            f"[bold cyan]{'='*60}[/bold cyan]",
+            f"[bold]{app.display_name}[/bold]",
+            f"[bold cyan]{'='*60}[/bold cyan]",
+            "",
+            "[bold]General[/bold]",
+            f"  Name:      {app.name}",
+            f"  Namespace: {app.namespace}",
+            f"  Project:   {app.project_name or '(unlinked)'}",
+            "",
+            "[bold]Build[/bold]",
+            f"  Status:    {app.build_status.value}",
+            f"  Builds:    {app.build_count}",
+            f"  Reason:    {app.build_reason or 'N/A'}",
+            f"  Stack:     {app.stack or 'N/A'}",
+            "",
+            "[bold]Source[/bold]",
+            f"  Git URL:   {app.git_url or 'N/A'}",
+            f"  Revision:  {app.git_revision or 'N/A'}",
+            "",
+            "[bold]Runtime[/bold]",
+            f"  Status:    {app.runtime_status.value}",
+            f"  Pods:      {app.pod_count}",
+            f"  URL:       {app.url or 'N/A'}",
+            "",
+            "[bold]Image[/bold]",
+            f"  Latest:    {app.latest_image[:60] + '...' if app.latest_image and len(app.latest_image) > 60 else app.latest_image or 'N/A'}",
+        ]
+        return "\n".join(lines)
+
+    def action_back(self) -> None:
+        """Go back."""
+        self.app.pop_screen()
+
+    def action_logs(self) -> None:
+        """View logs."""
+        self.app.switch_screen(LogsScreen(self.data_provider, self.app_info))
+
+    def action_rebuild(self) -> None:
+        """Rebuild app."""
+        self.app.push_screen(ConfirmScreen(
+            f"Rebuild '{self.app_info.display_name}'?",
+            self._do_rebuild
+        ))
+
+    def _do_rebuild(self) -> None:
+        """Execute rebuild."""
+        result = self.data_provider.rebuild_app(self.app_info.name)
+        if result:
+            self.notify(f"Rebuild triggered for {self.app_info.display_name}")
+        else:
+            self.notify(f"Failed to rebuild", severity="error")
+
+    def action_open_url(self) -> None:
+        """Open app URL in browser."""
+        if self.app_info.url:
+            import webbrowser
+            webbrowser.open(self.app_info.url)
+            self.notify(f"Opening {self.app_info.url}")
+        else:
+            self.notify("No URL available", severity="warning")
+
+
+class ProjectsScreen(Screen):
+    """Projects list screen."""
+
+    BINDINGS = [
+        Binding("q", "back", "Back"),
+        Binding("escape", "back", "Back", priority=True),
+        Binding("enter", "select", "Select"),
+        Binding("R", "refresh", "Refresh"),
+    ]
+
+    def __init__(self, data_provider: DataProvider, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.data_provider = data_provider
+        self.projects: List[ProjectInfo] = []
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield CommandBar(id="command-bar")
+        yield Container(
+            Static("Loading projects...", id="loading"),
+            DataTable(id="projects-table"),
+            id="main-container"
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Set up table and load data."""
+        cmd_bar = self.query_one("#command-bar", CommandBar)
+        cmd_bar.commands = CommandBar.format_commands([
+            ("Enter", "Select"),
+            ("R", "Refresh"),
+            ("Esc", "Back"),
+        ])
+
+        table = self.query_one("#projects-table", DataTable)
+        table.cursor_type = "row"
+        table.zebra_stripes = True
+
+        table.add_column("Name", key="name", width=30)
+        table.add_column("ID", key="id", width=40)
+        table.add_column("Namespace", key="namespace", width=20)
+
+        self.load_projects()
+
+    @work(exclusive=True)
+    async def load_projects(self) -> None:
+        """Load projects in background."""
+        worker = get_current_worker()
+        try:
+            projects = self.data_provider.get_projects()
+            if not worker.is_cancelled:
+                self.call_from_thread(self._update_table, projects)
+        except Exception as e:
+            if not worker.is_cancelled:
+                self.call_from_thread(self._show_error, str(e))
+
+    def _update_table(self, projects: List[ProjectInfo]) -> None:
+        """Update table with projects."""
+        self.projects = projects
+
+        loading = self.query_one("#loading", Static)
+        loading.display = False
+
+        table = self.query_one("#projects-table", DataTable)
+        table.display = True
+        table.clear()
+
+        for p in projects:
+            table.add_row(p.name, p.id, p.namespace, key=p.id)
+
+    def _show_error(self, message: str) -> None:
+        """Show error message."""
+        loading = self.query_one("#loading", Static)
+        loading.update(f"[red]Error: {message}[/red]")
+
+    def action_back(self) -> None:
+        """Go back."""
+        self.app.pop_screen()
+
+    def action_select(self) -> None:
+        """Select project and go to apps."""
+        table = self.query_one("#projects-table", DataTable)
+        if table.cursor_row is not None and self.projects:
+            row_key = table.get_row_key_at(table.cursor_row)
+            for p in self.projects:
+                if p.id == str(row_key.value):
+                    # TODO: Set project context
+                    self.notify(f"Selected project: {p.name}")
+                    self.app.pop_screen()
+                    break
+
+    def action_refresh(self) -> None:
+        """Refresh projects."""
+        loading = self.query_one("#loading", Static)
+        loading.update("Refreshing...")
+        loading.display = True
+        self.load_projects()
+
+
+class ConfirmScreen(Screen):
+    """Confirmation dialog screen."""
+
+    BINDINGS = [
+        Binding("y", "confirm", "Yes"),
+        Binding("n", "cancel", "No"),
+        Binding("escape", "cancel", "Cancel", priority=True),
+    ]
+
+    def __init__(self, message: str, on_confirm: callable, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.message = message
+        self.on_confirm = on_confirm
+
+    def compose(self) -> ComposeResult:
+        yield Container(
+            Static(f"[bold yellow]{self.message}[/bold yellow]", id="confirm-message"),
+            Horizontal(
+                Button("Yes (y)", id="yes-btn", variant="warning"),
+                Button("No (n)", id="no-btn", variant="primary"),
+                id="confirm-buttons"
+            ),
+            id="confirm-dialog"
+        )
+
+    def action_confirm(self) -> None:
+        """Confirm action."""
+        self.app.pop_screen()
+        self.on_confirm()
+
+    def action_cancel(self) -> None:
+        """Cancel action."""
+        self.app.pop_screen()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handle button press."""
+        if event.button.id == "yes-btn":
+            self.action_confirm()
+        else:
+            self.action_cancel()
+
+
+class HelpScreen(Screen):
+    """Help screen showing keyboard shortcuts."""
+
+    BINDINGS = [
+        Binding("q", "back", "Back"),
+        Binding("escape", "back", "Back", priority=True),
+    ]
+
+    def compose(self) -> ComposeResult:
+        yield Container(
+            Static(self._render_help(), id="help-content"),
+            id="help-container"
+        )
+        yield Footer()
+
+    def _render_help(self) -> str:
+        """Render help content."""
+        return """
+[bold cyan]╔══════════════════════════════════════════════════════════════╗[/bold cyan]
+[bold cyan]║[/bold cyan]           [bold white]Clue2App TUI - Quick Reference[/bold white]               [bold cyan]║[/bold cyan]
+[bold cyan]╚══════════════════════════════════════════════════════════════╝[/bold cyan]
+
+[bold green]┌─ NAVIGATION ─────────────────────────────────────────────────┐[/bold green]
+│                                                               │
+│  [bold cyan]↑[/bold cyan] or [bold cyan]k[/bold cyan]     Move selection up                             │
+│  [bold cyan]↓[/bold cyan] or [bold cyan]j[/bold cyan]     Move selection down                           │
+│  [bold cyan]Enter[/bold cyan]       Open / Select item                            │
+│  [bold cyan]Escape[/bold cyan]      Go back to previous screen                    │
+│  [bold cyan]q[/bold cyan]           Quit (from main screen) / Back                │
+│                                                               │
+[bold green]└───────────────────────────────────────────────────────────────┘[/bold green]
+
+[bold yellow]┌─ APPS SCREEN ─────────────────────────────────────────────────┐[/bold yellow]
+│                                                               │
+│  [bold cyan]Enter[/bold cyan]       View app details                             │
+│  [bold cyan]l[/bold cyan]           View app logs                                 │
+│  [bold cyan]r[/bold cyan]           Rebuild app (triggers new build)             │
+│  [bold cyan]d[/bold cyan]           Delete app (asks for confirmation)           │
+│  [bold cyan]p[/bold cyan]           Switch to projects view                       │
+│  [bold cyan]a[/bold cyan]           Toggle all projects / current project only   │
+│  [bold cyan]u[/bold cyan]           Toggle unlinked apps visibility              │
+│  [bold cyan]R[/bold cyan]           Refresh the list                             │
+│                                                               │
+[bold yellow]└───────────────────────────────────────────────────────────────┘[/bold yellow]
+
+[bold magenta]┌─ LOGS SCREEN ─────────────────────────────────────────────────┐[/bold magenta]
+│                                                               │
+│  [bold cyan]j[/bold cyan] / [bold cyan]k[/bold cyan]       Scroll down / up (one line)                  │
+│  [bold cyan]Ctrl+D[/bold cyan]      Scroll down half page                        │
+│  [bold cyan]Ctrl+U[/bold cyan]      Scroll up half page                          │
+│  [bold cyan]g[/bold cyan]           Jump to top of logs                          │
+│  [bold cyan]G[/bold cyan]           Jump to bottom of logs                       │
+│  [bold cyan]f[/bold cyan]           Toggle follow mode (live updates)            │
+│  [bold cyan]/[/bold cyan]           Search in logs                               │
+│  [bold cyan]n[/bold cyan]           Go to next search match                      │
+│  [bold cyan]N[/bold cyan]           Go to previous search match                  │
+│                                                               │
+[bold magenta]└───────────────────────────────────────────────────────────────┘[/bold magenta]
+
+[bold blue]┌─ DETAILS SCREEN ───────────────────────────────────────────────┐[/bold blue]
+│                                                               │
+│  [bold cyan]l[/bold cyan]           View logs                                    │
+│  [bold cyan]r[/bold cyan]           Rebuild app                                  │
+│  [bold cyan]o[/bold cyan]           Open app URL in browser                      │
+│                                                               │
+[bold blue]└───────────────────────────────────────────────────────────────┘[/bold blue]
+
+[dim]Press [bold]q[/bold] or [bold]Escape[/bold] to close this help and return.[/dim]
+"""
+
+    def action_back(self) -> None:
+        """Close help."""
+        self.app.pop_screen()
+
+
+class Clue2AppTUI(App):
+    """Main Clue2App TUI application."""
+
+    CSS = """
+    #main-container {
+        height: 100%;
+        padding: 1;
+    }
+
+    #loading {
+        text-align: center;
+        padding: 2;
+    }
+
+    #apps-table {
+        height: 100%;
+    }
+
+    #status-bar {
+        dock: bottom;
+        height: 1;
+        background: $surface;
+        padding: 0 1;
+    }
+
+    #logs-container {
+        height: 100%;
+        padding: 1;
+        overflow-y: auto;
+    }
+
+    #logs-header {
+        padding: 0 0 1 0;
+    }
+
+    #logs-content {
+        height: auto;
+    }
+
+    #details-container {
+        height: 100%;
+        padding: 1;
+        overflow-y: auto;
+    }
+
+    #confirm-dialog {
+        align: center middle;
+        width: 60;
+        height: 10;
+        border: solid $primary;
+        padding: 1 2;
+    }
+
+    #confirm-message {
+        text-align: center;
+        padding: 1;
+    }
+
+    #confirm-buttons {
+        align: center middle;
+        height: 3;
+    }
+
+    #confirm-buttons Button {
+        margin: 0 1;
+    }
+
+    #help-container {
+        padding: 2;
+        overflow-y: auto;
+    }
+
+    #search-dialog {
+        align: center middle;
+        width: 60;
+        height: 5;
+        border: solid $primary;
+        padding: 1 2;
+        background: $surface;
+    }
+
+    #search-label {
+        padding: 0 0 1 0;
+    }
+
+    #search-input {
+        width: 100%;
+    }
+    """
+
+    TITLE = "Clue2App TUI"
+    BINDINGS = [
+        Binding("q", "quit", "Quit", show=True),
+    ]
+
+    def __init__(self, initial_screen: str = 'apps', *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.initial_screen = initial_screen
+        self.data_provider = DataProvider()
+
+    def on_mount(self) -> None:
+        """Set up initial screen."""
+        if self.initial_screen == 'projects':
+            self.push_screen(ProjectsScreen(self.data_provider))
+        else:
+            self.push_screen(AppsScreen(self.data_provider))