feat(admin): Add terminal-style SQL Shell for ClickHouse tracing

[phacops]

Summary

• Add terminal-style shell interfaces for ClickHouse queries in snuba-admin
• Tracing Shell: Terminal interface for tracing queries (after ClickHouse Tracing in nav)
• System Shell: Terminal interface for system queries (after System Queries in nav)
• Both shells share the same component with mode-specific features
• Shell pages inherit permissions from their parent pages (tracing/system-queries)
• GitHub-inspired dark theme with polished visual design

Screenshots

Features

Commands

Tracing Shell

• USE <storage> - Select storage
• SHOW STORAGES - List available storages
• PROFILE ON/OFF - Toggle profile event collection
• TRACE RAW/FORMATTED - Toggle trace output format
• HELP - Show available commands
• CLEAR - Clear terminal output

System Shell

• USE <storage> - Select storage
• HOST <host:port> - Select target host
• SHOW STORAGES / SHOW HOSTS - List available options
• SUDO ON/OFF - Toggle sudo mode (red border warning when enabled)
• HELP - Show available commands
• CLEAR - Clear terminal output

Extensible Command Parser

• Registry-based command definitions in command_parser.ts
• Each command defined with: pattern, parser function, and mode restrictions
• Easy to add new commands by adding entries to the COMMANDS array
• Commands automatically filtered by shell mode (tracing/system)

SQL Syntax Highlighting

• CodeMirror-based input with SQL language support
• GitHub Dark theme colors matching the shell aesthetic:
  • Keywords (SELECT, FROM, WHERE, etc.): red/coral (#ff7b72)
  • Strings: light blue (#a5d6ff)
  • Numbers: cyan (#79c0ff)
  • Comments: gray italic (#8b949e)
  • Functions: purple (#d2a8ff)
  • Special values (NULL, TRUE, FALSE): cyan bold (#79c0ff)

Compact Collapsible Results

• Results and trace output displayed in collapsible sections
• Click section header to expand/collapse
• Results section expanded by default, trace sections collapsed
• Badge showing row count, node count, or line count
• Compact table styling with smaller fonts and tight padding
• Long cell values truncated with ellipsis
• NULL values displayed in gray italic

Multi-line Input

• Input box supports multi-line SQL queries
• Auto-resizes based on content (up to 10 lines)
• Queries are normalized before sending to API (newlines collapsed to spaces)

Keyboard Shortcuts (clickhouse-client style)

Shortcut	Action
Enter	Execute command
Shift+Enter	Insert new line
Tab	Autocomplete storage/host name
↑ / ↓	Navigate command history
Ctrl+C	Clear current input
Ctrl+L	Clear screen
Ctrl+U	Delete from cursor to start of line
Ctrl+K	Delete from cursor to end of line
Ctrl+W	Delete word before cursor
Ctrl+A	Move cursor to start of line
Ctrl+E	Move cursor to end of line

Autocomplete

• Press Tab after USE to autocomplete storage names
• Press Tab after HOST to autocomplete host names (system shell)
• Shows suggestions bar above input when multiple matches exist
• Click suggestions to select directly

Virtualized Scrollback

• Uses @tanstack/react-virtual for windowed virtualization of history entries
• Only visible entries plus 5 overscan items are rendered to the DOM
• Dynamic height measurement for accurate positioning of variable-height entries
• Smart auto-scroll: follows new entries only when user is at bottom
• Maximum history limit of 500 entries (~250 command/response pairs) to prevent unbounded growth

Scrollable Navigation Sidebar

• Navigation sidebar now scrolls when there are more items than fit in the viewport
• Prevents layout issues when many nav items are present

Visual Design

• GitHub-inspired dark terminal aesthetic
• Gradient backgrounds (#0d1117 → #161b22)
• Custom scrollbars matching theme
• Styled result tables with hover effects
• Error messages with red accent border (stack traces stripped for cleaner display)
• Animated executing indicator
• Sudo mode: red gradient background with glowing border

Error Handling

• Properly handles API error objects with {code, message, type} structure
• Strips ClickHouse stack traces from error messages for cleaner display
• Defensive checks for null/undefined results and trace data
• Graceful handling of malformed or missing data

Other Features

• Command history persisted to localStorage (per shell mode)
• Full-height shell using all available screen space
• Query results displayed in formatted tables (first 100 rows)
• NULL values displayed explicitly
• Trace output with formatted summaries or raw mode
• Profile events display
• Status bar showing current storage, host, and settings

Test plan

• Run snuba-admin locally with snuba admin --debug
• Verify "💻 Tracing Shell" appears after ClickHouse Tracing
• Verify "💻 System Shell" appears after System Queries
• Test shell commands: HELP, USE, SHOW STORAGES
• Test Tab autocomplete for storage names
• Test keyboard shortcuts (Ctrl+C, Ctrl+L, Ctrl+U, Ctrl+W, etc.)
• Test SQL query execution in both shells
• Test multi-line input with Shift+Enter
• Verify SQL syntax highlighting (keywords, strings, numbers, comments)
• Test collapsible results sections (click to expand/collapse)
• Test error handling (invalid queries should show clean error messages)
• Test command history navigation with Up/Down arrows
• Verify shell pages respect same permissions as parent pages
• Test sudo mode visual warning in system shell
• Execute 20+ queries to build history, verify smooth scrolling
• Scroll up, execute query, verify scroll position is preserved
• Verify navigation sidebar scrolls when window is short

🤖 Generated with Claude Code