ext.faiz.hidayat/nebara-tui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
43b8bfa253cb3636d0b20be2331f51e770613238
nebara-tui/README.md
T

9.7 KiB
Raw Blame History

Nebara OS TUI — Visual Baseline v0.1

Native terminal management interface for the Nebara S3GX Appliance, implemented in Go using tview + tcell/v2.

Important

This is a visual prototype using mock appliance data only. No real system configuration, privileged operations, or hardware interaction occurs.

Overview

Nebara OS is a common appliance operating environment for enterprise infrastructure products. This prototype establishes the TUI visual foundation for the Nebara S3GX Appliance, reproducing the Figma reference mockups as faithfully as a native terminal environment allows.

The interface is intentionally minimal and industrial — inspired by enterprise console UIs like VMware ESXi DCUI.

Prerequisites

Requirement Version
Go ≥ 1.21
Terminal True-color 256+ color support
Recommended font JetBrains Mono (any weight)

Check Go version

go version

Build

git clone <repo>
cd nebara-os
go mod tidy
go build -o nebara-tui ./cmd/nebara-tui

On Windows:

go build -o nebara-tui.exe ./cmd/nebara-tui

Run

# Warning state (default) with SIXEL logo
./nebara-tui --mock-state=warning --sixel=true

# Normal state with SIXEL logo
./nebara-tui --mock-state=normal --sixel=true

# Fallback to pure text colored logo
./nebara-tui --sixel=false

Or via go run:

go run ./cmd/nebara-tui --mock-state=warning --sixel=true
go run ./cmd/nebara-tui --mock-state=normal --sixel=false

Mock States

State A — Warning (--mock-state=warning)

Field Value
Product Nebara S3GX Appliance
Version 1.0.1
Hostname jkt-s3gx-lin-01.domain.local
Address 10.249.23.13/26
Uptime 132d 12h 32m
Status Healthy
Message [Warn] Update Available to version 2.1.4!
Initial selection Security & Access

State B — Normal (--mock-state=normal)

Field Value
Product Nebara S3GX Appliance
Version 2.1.4
Hostname sin-s3gx-lin-05.domain.local
Address 10.175.15.11/25
Uptime 111d 14h 21m
Status Healthy
Message None
Initial selection System Maintenance

Keyboard Controls

Key Action
↑ / ↓ Navigate menu items
Enter Open submenu or confirm
Esc Return to parent menu
Home Jump to first item
End Jump to last item
F1 Show keyboard shortcut help
Ctrl+C Quit application

Recommended Terminal Settings

For the best visual experience:

  • Font: JetBrains Mono (Regular / Bold) — available from jetbrains.com/lp/mono
  • Color support: True-color (24-bit) — set COLORTERM=truecolor if needed
  • Background: Black (#000000) — ensure terminal background matches
  • Minimum size: 60 columns × 20 rows (warning shown if smaller)
  • Recommended size: 120 columns × 40 rows or larger

Windows Terminal

{
  "font": { "face": "JetBrains Mono", "size": 14 },
  "colorScheme": "One Half Dark"
}

Set COLORTERM=truecolor in your shell profile for 24-bit colors.

Responsive Layout

The layout adapts to terminal dimensions using percentage-based margins derived from the Figma reference (1920×1080, 80px outer margins ≈ 4.17% of width):

Terminal Size Behavior
192×54 and wider Spacious; full Figma proportions
120×40 Normal desktop; full metadata
100×30 Compact; reduced whitespace
80×24 Minimum practical target; message row suppressed below 24 rows
Below 60×20 Size warning overlay; no crash

Live resizing is handled; no restart required.

Project Structure

nebara-os/
├── cmd/
│   └── nebara-tui/
│       └── main.go              # CLI entry point, --mock-state flag
│
├── internal/
│   ├── app/
│   │   ├── application.go       # TUI wiring: layout, callbacks, modals
│   │   └── state.go             # Runtime application state struct
│   │
│   ├── model/
│   │   ├── appliance.go         # ApplianceInfo data model
│   │   ├── message.go           # SystemMessage + severity types
│   │   └── menu.go              # MenuItem tree + MainMenu() factory
│   │
│   ├── ui/
│   │   ├── theme/
│   │   │   └── colors.go        # Centralized color tokens & tcell styles
│   │   │
│   │   ├── layout/
│   │   │   └── responsive.go    # Terminal→cell layout constraint calculator
│   │   │
│   │   ├── components/
│   │   │   ├── header.go        # Header, ApplianceInfo, Message, Description, Footer
│   │   │   └── menu.go          # Custom MenuWidget (full-width row highlight)
│   │   │
│   │   └── navigation/
│   │       └── navigator.go     # Navigation stack (Enter/Back/Up/Down)
│   │
│   └── mock/
│       └── states.go            # WarningState() and NormalState() factories
│
├── go.mod
├── go.sum
└── README.md

Design System

Colors

Token Hex Usage
Background #000000 Main screen background
Primary #F5F5F5 Default foreground text
Secondary #BBBBBB Labels, descriptions, borders
Selection BG #BBBBBB Selected menu row background
Selection FG #000000 Selected menu row text
Warning #FFCC00 Warning message text
Error #B30D18 Error messages; logo "O" accent
Info #0088FF Informational messages

Typography Hierarchy

The terminal cannot control font family per-component. Hierarchy is expressed through:

  • Bold — product title, footer key labels
  • Regular — metadata labels, values, menu items, descriptions
  • Color — severity-classified messages, logo accent

Known Terminal Rendering Limitations

Figma Specification Terminal Equivalent
Michroma 24px logo font Terminal monospace font; layout preserved
JetBrains Mono Bold/Regular by size Bold attribute; font configured per-terminal
1px border (outside alignment) Single-cell-width tview box border
Pixel-precise spacing Cell-based proportional spacing
Shadow effects Not reproducible in terminals
Rounded corners Not applicable; square box characters used
True-color hex values Full 24-bit color via tcell on supported terminals

Testing

go test ./...           # Run all tests
go test ./... -v        # Verbose output
go vet ./...            # Static analysis
go fmt ./...            # Format check

Test Coverage

Package Tests
internal/mock Mock state correctness, message visibility
internal/ui/layout Margin clamping, message visibility, compact behavior
internal/ui/navigation All navigation transitions, stack depth, breadcrumbs

Manual Validation Steps

  1. Launch both mock states and compare against reference screenshots
  2. Navigate all 6 main menu items with ↑/↓ — verify description updates
  3. Press Enter on each main menu item — verify submenu appears with correct title
  4. Navigate submenu items — verify ↑/↓ work
  5. Press Esc from submenu — verify return to main menu with original selection
  6. Press Enter on a leaf (submenu item) — verify not-implemented modal appears
  7. Press F1 — verify help modal appears
  8. Resize terminal live — verify no flickering or corruption
  9. Shrink below 60×20 — verify size warning appears

SIXEL Logo Integration POC

The application includes an experimental, isolated proof-of-concept for rendering the official PNG logo using native SIXEL graphics escape sequences:

Technical Architecture

  1. Embedded Asset: The official 221×19 px PNG logo is embedded via //go:embed inside internal/ui/sixel.
  2. SIXEL Encoding: The asset is converted into DECSIXEL format at startup via github.com/mattn/go-sixel, producing a compact 3.9 KB payload.
  3. Screen Buffer Synchronization (screen.LockRegion): During header rendering, the 26-column × 1-row area occupied by the logo is locked in tcell.Screen. This guarantees tcell's dirty cell tracking skips those coordinates, preventing the screen engine from overwriting the graphic with background spaces or text on subsequent redraw cycles.
  4. Direct-to-TTY Output: The SIXEL payload is written directly to the terminal output device (CONOUT$ on Windows, /dev/tty on UNIX) with ANSI cursor save (\x1b[s), positioning (\x1b[%d;%dH), and restore (\x1b[u).
  5. Redraw & Resize Lifecycle: The logo automatically re-emits when terminal geometry changes (e.g., live window resize) or when modal overlays (such as the F1 Help dialog) are dismissed.
  6. Deadlock Prevention: SetFocus() is strictly avoided inside draw callbacks (SetBeforeDrawFunc), ensuring mutex safety during live window resizing.
  7. Graceful Fallback: Pass --sixel=false or resize below minimum width to revert seamlessly to the colored text logo.

Future Integration Boundaries

This prototype establishes the visual foundation. Future phases will:

  • Connect to a privileged management daemon via Unix socket or gRPC
  • Add real ApplianceInfo collection (hostname, IP, uptime) without root
  • Implement System Configuration, Network Configuration, etc. as real forms
  • Support product-specific modules (UNFZFS, Tape, Backup) via adapter pattern
  • Add authentication gate before main menu on production builds

The TUI must never require root privileges. Privileged operations route through a separate daemon.

Nebara OS TUI — Visual Baseline v0.1 — Prototype only — Mock data only

Reference in New Issue View Git Blame Copy Permalink