Fully autonomous AI Agents system capable of performing complex penetration testing tasks
BaseScreen Architecture Guide
Practical guide for implementing new installer screens and migrating existing ones using the BaseScreen architecture.
ποΈ Architecture Overview
The BaseScreen provides a unified foundation for all installer form screens, encapsulating:
- State Management:
initialized,hasChanges,focusedIndex,showValues - Form Handling:
fields []FormField, viewport management, auto-scrolling - Navigation: Composite ScreenID support, GoBack patterns
- Layout: Responsive horizontal/vertical layouts
- Lists: Optional dropdown lists with delegates
Core Components
type BaseScreen struct {
// Dependencies (injected)
controller *controllers.StateController
styles *styles.Styles
window *window.Window
// State
initialized bool
hasChanges bool
focusedIndex int
showValues bool
// Form data
fields []FormField
fieldHeights []int
// UI components
viewport viewport.Model
formContent string
// Handlers (must be implemented)
handler BaseScreenHandler
listHandler BaseListHandler // optional
}
Required Interfaces
type BaseScreenHandler interface {
BuildForm() tea.Cmd
GetFormSummary() string
GetFormTitle() string
GetHelpContent() string
HandleSave() error
HandleReset()
OnFieldChanged(fieldIndex int, oldValue, newValue string)
GetFormFields() []FormField
SetFormFields(fields []FormField)
}
type BaseListHandler interface { // Optional
GetList() *list.Model
OnListSelectionChanged(oldSelection, newSelection string)
GetListHeight() int
}
π Creating New Screens
1. Basic Form Screen
// example_form.go
type ExampleFormModel struct {
*BaseScreen
config *controllers.ExampleConfig
}
func NewExampleFormModel(
controller *controllers.StateController,
styles *styles.Styles,
window *window.Window,
args []string,
) *ExampleFormModel {
m := &ExampleFormModel{
config: controller.GetExampleConfig(),
}
m.BaseScreen = NewBaseScreen(controller, styles, window, args, m, nil)
return m
}
// Required interface implementations
func (m *ExampleFormModel) BuildForm() {
fields := []FormField{}
// Text field
apiKeyInput := textinput.New()
apiKeyInput.Placeholder = "Enter API key"
apiKeyInput.EchoMode = textinput.EchoPassword
apiKeyInput.SetValue(m.config.APIKey)
fields = append(fields, FormField{
Key: "api_key",
Title: "API Key",
Description: "Your service API key",
Required: true,
Masked: true,
Input: apiKeyInput,
Value: apiKeyInput.Value(),
})
// Boolean field
enabledInput := textinput.New()
enabledInput.Placeholder = "true/false"
enabledInput.ShowSuggestions = true
enabledInput.SetSuggestions([]string{"true", "false"})
enabledInput.SetValue(fmt.Sprintf("%t", m.config.Enabled))
fields = append(fields, FormField{
Key: "enabled",
Title: "Enabled",
Description: "Enable or disable service",
Required: false,
Masked: false,
Input: enabledInput,
Value: enabledInput.Value(),
})
m.SetFormFields(fields)
}
func (m *ExampleFormModel) GetFormTitle() string {
return "Example Service Configuration"
}
func (m *ExampleFormModel) GetHelpContent() string {
return "Configure your Example service settings here."
}
func (m *ExampleFormModel) HandleSave() error {
fields := m.GetFormFields()
for _, field := range fields {
switch field.Key {
case "api_key":
m.config.APIKey = field.Input.Value()
case "enabled":
m.config.Enabled = field.Input.Value() == "true"
}
}
if m.config.APIKey == "" {
return fmt.Errorf("API key is required")
}
return m.GetController().UpdateExampleConfig(m.config)
}
func (m *ExampleFormModel) HandleReset() {
m.config = m.GetController().GetExampleConfig()
m.BuildForm()
}
func (m *ExampleFormModel) OnFieldChanged(fieldIndex int, oldValue, newValue string) {
// Additional validation logic if needed
}
func (m *ExampleFormModel) GetFormFields() []FormField {
return m.BaseScreen.fields
}
func (m *ExampleFormModel) SetFormFields(fields []FormField) {
m.BaseScreen.fields = fields
}
// Update method with field input handling
func (m *ExampleFormModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
switch msg.String() {
case "tab":
// Handle tab completion for boolean fields
return m.handleTabCompletion()
default:
// Handle field input
if cmd := m.HandleFieldInput(msg); cmd != nil {
return m, cmd
}
}
}
// Base screen handling
return m.BaseScreen.Update(msg)
}
2. Screen with List Selection
// list_form.go
type ListFormModel struct {
*BaseScreen
config *controllers.ListConfig
selectionList list.Model
delegate *ExampleDelegate
}
func NewListFormModel(...) *ListFormModel {
m := &ListFormModel{
config: controller.GetListConfig(),
}
m.initializeList()
m.BaseScreen = NewBaseScreen(controller, styles, window, args, m, m) // Both handlers
return m
}
func (m *ListFormModel) initializeList() {
items := []list.Item{
ExampleOption("Option 1"),
ExampleOption("Option 2"),
}
m.delegate = &ExampleDelegate{
style: m.GetStyles().FormLabel,
width: MinMenuWidth - 6,
}
m.selectionList = list.New(items, m.delegate, MinMenuWidth-6, 3)
m.selectionList.SetShowStatusBar(false)
m.selectionList.SetFilteringEnabled(false)
m.selectionList.SetShowHelp(false)
m.selectionList.SetShowTitle(false)
}
// BaseListHandler implementation
func (m *ListFormModel) GetList() *list.Model {
return &m.selectionList
}
func (m *ListFormModel) OnListSelectionChanged(oldSelection, newSelection string) {
m.config.SelectedOption = newSelection
m.BuildForm() // Rebuild form based on selection
}
func (m *ListFormModel) GetListHeight() int {
return 5
}
func (m *ListFormModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
// Handle list input first
if cmd := m.HandleListInput(msg); cmd != nil {
return m, cmd
}
// Then field input
if cmd := m.HandleFieldInput(msg); cmd != nil {
return m, cmd
}
}
return m.BaseScreen.Update(msg)
}
The two examples above predate two changes to the base:
NewBaseScreenno longer takes anargs []stringparameter, andBuildForm()now returns atea.Cmd. The two screens below are written against the current shape.
3. Document Screen (viewport, no BaseScreen)
wizard/models/update_overview.go is the shape to copy when a screen shows text rather than fields. It does not embed BaseScreen at all β it implements BaseScreenModel directly, the way eula.go does.
Everything BaseScreen contributes (fields, focus, save/reset, the form/help split) is dead weight for a document, and the one thing a document needs β a full-width scrolling viewport over rendered markdown β BaseScreen does not provide.
type UpdateOverviewModel struct {
styles styles.Styles
window window.Window
controller controller.Controller
viewport viewport.Model
source string // the markdown
content string // that markdown, rendered at renderedAt columns
renderedAt int
ready bool
scrolled bool
}
// only the model interface: there is no form, so there is no handler
var _ BaseScreenModel = (*UpdateOverviewModel)(nil)
Keep the markdown and its rendered form as two separate fields. A resize re-renders from the source. Re-wrapping the already-rendered string would wrap the ANSI escape sequences glamour wrote into it, and the screen fills with fragments of colour codes.
Re-render only when the wrap width actually changed:
func (m *UpdateOverviewModel) updateViewport() {
contentWidth, contentHeight := m.window.GetContentSize()
if contentWidth <= 0 || contentHeight <= 0 || m.source == "" {
return
}
if m.content == "" || m.renderedAt != contentWidth {
rendered, err := m.styles.GetRendererForWidth(contentWidth).Render(m.source)
// ... on error, fall back to the raw markdown plus the error
m.content = rendered
m.renderedAt = contentWidth
}
if !m.ready {
m.viewport = viewport.New(contentWidth, contentHeight)
m.ready = true
} else {
m.viewport.Width, m.viewport.Height = contentWidth, contentHeight
}
m.viewport.SetContent(m.content)
m.updateScrollStatus()
}
Dragging a window border delivers one tea.WindowSizeMsg per column and glamour is not cheap, so renderedAt is what stops the whole changelog being re-rendered for a resize that cannot change how it wraps β a height-only drag, or one of the resizes registry.HandleMsg forwards to every registered screen whether or not the user is looking at it. The comparison is against the raw content width, so widths outside the clamp band below still re-render (into identical output); the renderer itself is memoised in either case.
Create the viewport on the first real size, never in the constructor.window.GetContentSize() is 0Γ0 until the first WindowSizeMsg arrives, and a viewport built at that size shows nothing afterwards. ready is the flag that says the viewport exists, and each of its readers does something different: View() falls back to the loading text, GetScrollInfo() returns zeroes rather than measure an unsized viewport, and every scrolling key sits behind an if !m.ready { break } guard.enter is deliberately in front of that guard β continuing needs no rendered document, so the one action the screen offers is never blocked by a size message that has not arrived yet.
Deliver the content as a message even when nothing is fetched.loadOverview only reads the last check result out of the controller and cannot fail, but it is still a tea.Cmd returning UpdateOverviewLoadedMsg β the same shape as the EULA screen, and it keeps Init() the single place that decides what a fresh visit shows.
GetFormTitle() returns the empty string.
The document carries its own H1, and the header would otherwise print the heading twice.
GetScrollInfo() (scrolled, atEnd bool, percent int) is the accessor a footer uses to show scroll position; it returns zeroes while !ready rather than reading an unsized viewport.app.renderFooter consults it only on the EULA screen today, which needs "you have reached the end" for consent.
This screen instead announces what the keys do, and only once there is something to scroll:
func (m *UpdateOverviewModel) GetFormHotKeys() []string {
hotkeys := []string{"enter"}
if m.ready && m.content != "" {
hotkeys = append(hotkeys, "up|down", "pgup|pgdown", "home|end")
}
return hotkeys
}
Build the document in a pure function.
overviewDocument(updates []checker.StackUpdate, checkSucceeded bool) string lives
outside the model and update_overview_test.go tests that function. There is no
harness for a bubbletea screen in the wizard, and what is worth testing is what the
document says, not how it scrolls.
4. Action Screen with a Terminal Panel
wizard/models/installer_update.go is the other new shape: no form fields at all, but
the BaseScreen layout and help panel are worth keeping. It embeds BaseScreen,
implements BaseScreenHandler with empty form plumbing, and puts a
terminal.Terminal where the form viewport would be.
type InstallerUpdateModel struct {
*BaseScreen
processor processor.ProcessorModel
terminal terminal.Terminal
offered *processor.InstallerPackage // what the server offers
offerErr error // ...or why there is none
running bool
confirming bool
}
var _ BaseScreenModel = (*InstallerUpdateModel)(nil)
var _ BaseScreenHandler = (*InstallerUpdateModel)(nil)
BuildForm() builds the panel, not fields β and sets initialized itself:
func (m *InstallerUpdateModel) BuildForm() tea.Cmd {
m.SetFormFields([]FormField{}) // action screen: nothing to focus, nothing to save
contentWidth, contentHeight := m.getViewportFormSize()
if m.terminal == nil {
if !m.isVerticalLayout() {
contentWidth -= 2
}
m.terminal = terminal.NewTerminal(contentWidth-2, contentHeight-1,
terminal.WithAutoScroll(), terminal.WithAutoPoll(), terminal.WithCurrentEnv())
} else {
m.terminal.Clear()
}
m.terminal.Append(locale.InstallerUpdateAsking)
if !m.initialized {
m.initialized = true
return m.terminal.Init()
}
return nil
}
The overridden View() also calls BuildForm() while !initialized and discards the command it returns. Without setting the flag here, every frame would clear the panel and re-append the first line, wiping out the output of a running download on each redraw.
Re-size the terminal by hand. The terminal is not part of the BaseScreen viewports, so updateViewports() does not manage it. In the tea.WindowSizeMsg branch, the same arithmetic from BuildForm is repeated (getViewportFormSize(), subtracting two columns in horizontal layout and accounting for the border) before calling m.terminal.SetSize(...). It is important to keep these two pieces of arithmetic in sync.
Never let key messages fall through to BaseScreen. In the base screen logic, enter means save-and-return and ctrl+r means reset. On an action screen, this behavior is undesirable, as pressing enter could exit mid-download. Therefore, the tea.KeyMsg branch for this model handles enter, y, and n itself and passes all other keys to the terminal for scrolling. While m.terminal.IsRunning() is true, every key message goes directly to the terminal unfiltered, making the screen's own keys unreachable by construction rather than by explicit checks.
Load asynchronously, and carry the failure in the same message.
func (m *InstallerUpdateModel) Init() tea.Cmd {
m.running, m.confirming = false, false
m.offered, m.offerErr = nil, nil
return tea.Batch(m.BaseScreen.Init(), m.loadPackage)
}
type InstallerPackageLoadedMsg struct {
Package *processor.InstallerPackage
Err error
}
Registry screens are singletons that are built once at start-up, but Init() runs on every navigation to the screen. This means per-visit state has to be cleared here. Otherwise, on a second visit, the screen would display the previous answer, and if confirming were still set, pressing y could act on an outdated offer. Both the package and error outcomes travel in a single message and are stored, because the logic for allowing a download is based on canDownload()βdefined as !running && offered != nil && offerErr == nil. If the screen fails to load the package, it becomes inactive: pressing enter has no effect, and GetFormHotKeys() returns no keys to show available actions.
A confirmation only where there is a question. Pressing enter starts the download immediately. The confirmation prompt appears only if the file about to be written already existsβonly in this case do y and n have meaning. The hotkeys are managed to match these three states exactly, ensuring that the footer never suggests a key that the screen would ignore.
func (m *InstallerUpdateModel) GetFormHotKeys() []string {
if m.terminal != nil && m.terminal.IsRunning() {
return nil
}
if m.confirming {
return []string{"y|n"}
}
if !m.canDownload() {
return nil
}
return []string{"enter"}
}
Note that this shadows BaseScreen.GetFormHotKeys(). The base gates down|up, ctrl+s, and ctrl+r behind having fields or a list, so on a screen with neither it offers none of them β but it appends enter unconditionally. enter is exactly the key this screen has to be able to withhold: while the download is running, and on a screen whose offer never arrived, pressing it does nothing and the footer must not say otherwise.
The declining branch matters as much as the confirming one: n clears confirming and rewrites the panel with what the user now needs, rather than returning to a screen that still reads as if nothing happened.
Text in a pure function, again. installerUpdateLines(running, offered, err) returns the panel contents as []string, so installer_update_test.go can assert what the screen claims without a terminal.
π Migrating Existing Screens
Step 1: Analyze Current Screen
From existing screen, identify:
- Form fields and their types
- List components (if any)
- Special keyboard handling
- Save/reset logic
Step 2: Refactor Structure
// Before:
type OldFormModel struct {
controller *controllers.StateController
styles *styles.Styles
window *window.Window
args []string
initialized bool
hasChanges bool
focusedIndex int
showValues bool
fields []FormField
viewport viewport.Model
formContent string
fieldHeights []int
// ... config-specific fields
}
// After:
type NewFormModel struct {
*BaseScreen // Embedded base screen
// Only config-specific fields
config *controllers.Config
list list.Model // If needed
}
Step 3: Update Constructor
// Before:
func NewOldFormModel(...) *OldFormModel {
return &OldFormModel{
controller: controller,
styles: styles,
// ... lots of boilerplate
}
}
// After:
func NewNewFormModel(...) *NewFormModel {
m := &NewFormModel{
config: controller.GetConfig(),
}
// Initialize list if needed
m.initializeList()
m.BaseScreen = NewBaseScreen(controller, styles, window, m, m)
return m
}
Step 4: Implement Required Interfaces
Move existing methods to interface implementations:
// Move: buildForm() β BuildForm()
// Move: save logic β HandleSave()
// Move: reset logic β HandleReset()
// Move: help content β GetHelpContent()
Step 5: Remove Redundant Methods
Delete these methods from migrated screens:
getInputWidth(),getViewportSize(),updateViewport()focusNext(),focusPrev(),toggleShowValues()renderVerticalLayout(),renderHorizontalLayout()ensureFocusVisible()
π Environment Variable Integration
Follow existing patterns for environment variable handling:
func (m *FormModel) BuildForm() tea.Cmd {
// Track initially set fields for cleanup
m.initiallySetFields = make(map[string]bool)
for _, fieldConfig := range m.fieldConfigs {
envVar, _ := m.GetController().GetVar(fieldConfig.EnvVarName)
m.initiallySetFields[fieldConfig.Key] = envVar.IsPresent()
field := m.createFieldFromEnvVar(fieldConfig, envVar)
fields = append(fields, field)
}
m.SetFormFields(fields)
return nil // a form screen has nothing to start; only a panel screen returns a cmd
}
func (m *FormModel) HandleSave() error {
// First pass: Remove cleared fields
for _, field := range m.GetFormFields() {
value := strings.TrimSpace(field.Input.Value())
if value == "" && m.initiallySetFields[field.Key] {
m.GetController().SetVar(field.EnvVarName, "")
}
}
// Second pass: Save non-empty values
for _, field := range m.GetFormFields() {
value := strings.TrimSpace(field.Input.Value())
if value != "" {
m.GetController().SetVar(field.EnvVarName, value)
}
}
return nil
}
π― Navigation Integration
Screen Registration β four mandatory steps
All four are required. Skipping any of them fails quietly: nothing panics and nothing is logged. Three of them show a symptom somewhere other than the code you changed; the fourth β step 2 β shows no symptom at all with the screens written so far, which is exactly why it is the one that gets skipped.
1. The ScreenID constant in wizard/models/types.go:
const (
ExampleFormScreen ScreenID = "example_form"
// parameterised screens join their arguments with "Β§"
UpdatePentagiScreen ScreenID = "processor_operation_formΒ§composeΒ§update"
)
The ID is the only key the navigator, the registry and every menu share. Without it there is nothing to push onto the navigation stack and nothing to key the registry by.
2. A case in models.RestoreModel (types.go):
case *ExampleFormModel:
return m
app.forwardMsgToCurrentModel calls Update on the current model and adopts the result only when RestoreModel recognises it β when it returns nil there is no fallback and no log: the app keeps the pointer it already holds, and returns the command either way. What a missing branch actually costs is worth stating precisely, because the obvious answer is wrong. Every screen in wizard/models has a pointer receiver on Update and returns itself, so the object the app renders is the object Update has just mutated β nothing freezes, and a missing branch shows no symptom at all. The branch is load-bearing for the case the type allows but nobody has written yet: a model that returns a different model, dropped silently with nothing anywhere to say why. That is why the contract is "every screen is listed" rather than "list the ones that need it" β the day a screen starts returning something else is not the day anybody remembers this rule. The nil is load-bearing in the other direction too: a MaintenanceModel delegates Update to its embedded *ListScreen, which returns itself, and RestoreModel not knowing *ListScreen is exactly what keeps the app pointing at the whole screen instead of one of its parts β so list the concrete screen type and nothing else.
TestTypes_RestoreModel_RestoresTheUpdateScreens in types_test.go pins membership:
for _, model := range []tea.Model{(*InstallerUpdateModel)(nil), (*UpdateOverviewModel)(nil)} {
if RestoreModel(model) == nil {
t.Errorf("%T is missing its branch in RestoreModel", model)
}
}
3. Construction in registry.initScreens (wizard/registry/registry.go):
r.screens[models.ExampleFormScreen] = models.NewExampleFormModel(r.controller, r.styles, r.window)
Screens are built once here and reused; registry.GetScreen falls back to a MockFormModel for an unknown ID and caches it under that ID, so the screen you wrote is never constructed at all. The first symptom is not the screen but the menu: ListScreen labels each entry by asking the registry for the model behind its ID (GetFormName, GetFormOverview, GetCurrentConfiguration, IsConfigured), so the entry reads "Development Screen" and opens a placeholder. An unregistered screen also never receives tea.WindowSizeMsg, which registry.HandleMsg forwards to registered screens only.
4. Strings in wizard/locale/locale.go, and hotkey captions in app.initHotkeysLocale (wizard/app.go). All user-visible text lives in locale; the footer resolves each name from GetFormHotKeys() through the caption map:
if localeHotKey, ok := app.hotkeys[hotkey]; ok {
actions = append(actions, localeHotKey)
}
An unknown name is skipped without complaint, so the key keeps working and is simply never announced β the quietest of the four failures, and the only one whose symptom is a hint that is missing rather than a screen that is wrong. Neither new screen needed a new caption: enter, up|down, pgup|pgdown, home|end and y|n are already in the map.
Width-aware markdown rendering
styles.GetRenderer() returns a single renderer built once with glamour.WithWordWrap(DefaultRenderWidth) β 80 columns, whatever the terminal is doing. That was enough while the only markdown screen was the EULA, which renders once at load and is prose written to be read at a fixed measure. It is not enough for a changelog: at 80 columns in a 200-column window the document uses a third of the screen, and in a terminal narrower than 80 every line breaks two or three times, which is what a list of component names does worst.
styles.GetRendererForWidth(width) is the replacement for screens that know how much room they have:
func (s *Styles) GetRendererForWidth(width int) *glamour.TermRenderer {
width = min(max(width, MinRenderWidth), MaxRenderWidth) // [40, 120]
// ... memoised per width; on any failure returns the fixed 80-column renderer
}
Four properties are worth knowing before you use it:
- It clamps to
[MinRenderWidth, MaxRenderWidth]=[40, 120]. The floor keeps a narrow terminal from splitting every line; the ceiling is a readability limit β a line spanning a maximised terminal is measurably harder to read. - It never returns
nil. A width that cannot be built falls back to the default renderer, so no render path needs a nil check β and a nil check that someone forgets is how a changelog ends up not being shown at all. - The cache is behind a pointer (
renderers *rendererCache), becausestyles.Stylesis copied by value into every screen and a value cache would be cloned per screen, defeating the point. - The cache is mutex-guarded, because renderers are built inside
tea.Cmdgoroutines β off the update loop, where two screens can ask for the same width at once.
GetRenderer() still exists and still wraps at 80; prefer GetRendererForWidth on anything that renders inside a sized panel.
Navigation Usage
// Navigate to screen with parameters
return m, func() tea.Msg {
return NavigationMsg{
Target: CreateScreenID("example_form", "config_type"),
}
}
// Return to previous screen
return m, func() tea.Msg {
return NavigationMsg{GoBack: true}
}
π§ Interface Validation
Add compile-time interface checks:
// Ensure interfaces are implemented
var _ BaseScreenHandler = (*ExampleFormModel)(nil)
var _ BaseListHandler = (*ListFormModel)(nil)
// A screen that embeds BaseScreen asserts both: the registry stores it as a model,
// and BaseScreen calls back into it as a handler
var _ BaseScreenModel = (*InstallerUpdateModel)(nil)
var _ BaseScreenHandler = (*InstallerUpdateModel)(nil)
// A document screen has no form, so it asserts only the model interface
var _ BaseScreenModel = (*UpdateOverviewModel)(nil)
π Benefits Summary
- Code Reduction: 50-60% less boilerplate per screen
- Consistency: Unified behavior across all forms
- Maintainability: Centralized bug fixes and improvements
- Development Speed: Faster new screen implementation
π― Quick Reference
Screen Types
- Simple Form: Inherit BaseScreen, implement BaseScreenHandler
- Form with List: Inherit BaseScreen, implement both handlers
- Menu Screen: Use existing patterns without BaseScreen
- Document: No BaseScreen β implement BaseScreenModel over a viewport (
eula.go,update_overview.go) - Action with terminal panel: Inherit BaseScreen with zero fields, own the terminal and override
View()(installer_update.go,apply_changes.go)
Required Methods
BuildForm()- Create form fieldsHandleSave()- Save configuration with validationHandleReset()- Reset to defaultsGetFormTitle()- Screen titleGetHelpContent()- Right panel content
Optional Methods
OnFieldChanged()- Real-time validation- List handler methods (if using lists)
This architecture enables rapid development of new installer screens while maintaining consistency and reducing code duplication.