nebara-tui/README.md

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) — matches Figma Mock State A
./nebara-tui --mock-state=warning

# Normal state — matches Figma Mock State B
./nebara-tui --mock-state=normal

Or via go run:

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

---

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

---

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