ui

type Action ¶ added in v0.13.0

type Action struct {
	Command string
	Note    string
}

Action is a command the reader can run next, with a short note on what it does. Commands are never wrapped, so they stay copy-pasteable.

type Column ¶

type Column struct {
	Title      string
	Width      int
	NoTruncate bool // If true, this column won't be truncated when scaling
	WordWrap   bool // If true, text that exceeds Width is wrapped instead of truncated
}

Column defines a table column with title and width

func AutoSizeColumns(headers []string, rows []Row, builder *ColumnBuilder) []Column

type ColumnBuilder ¶ added in v0.0.2

type ColumnBuilder struct {
	// contains filtered or unexported fields
}

ColumnBuilder helps configure column options using a fluent API

func Columns() *ColumnBuilder

func (b *ColumnBuilder) MaxWidth(index, width int) *ColumnBuilder

func (b *ColumnBuilder) MinWidth(index, width int) *ColumnBuilder

func (b *ColumnBuilder) NoTruncate(indices ...int) *ColumnBuilder

func (b *ColumnBuilder) WordWrap(indices ...int) *ColumnBuilder

type ColumnHint ¶ added in v0.0.2

type ColumnHint struct {
	MaxWidth   int  // Maximum width (0 = no limit)
	NoTruncate bool // If true, this column won't be scaled down
	MinWidth   int  // Minimum width when scaling (0 = use default)
	WordWrap   bool // If true, wrap text instead of truncating
}

ColumnHint provides configuration hints for a specific column

type ConfirmOption ¶

type ConfirmOption func(*confirmConfig)

ConfirmOption configures a confirmation prompt

func WithAffirmative(text string) ConfirmOption

func WithDefault(defaultYes bool) ConfirmOption

func WithIndent(indent string) ConfirmOption

func WithMessage(message string) ConfirmOption

func WithNegative(text string) ConfirmOption

type Definition ¶ added in v0.3.1

type Definition struct {
	Term        string
	Description string
	Details     []DefinitionDetail
}

Definition represents a single definition entry with a term, description, and optional details

type DefinitionDetail ¶ added in v0.3.1

type DefinitionDetail struct {
	Name     string
	Type     string
	Required bool
}

DefinitionDetail represents a child item in a definition (displayed as a tree)

type DefinitionList ¶ added in v0.3.1

type DefinitionList struct {
	// contains filtered or unexported fields
}

DefinitionList renders a list of definitions with tree-style details

func NewDefinitionList(items []Definition, opts ...DefinitionListOption) *DefinitionList

func (d *DefinitionList) Render() string

type DefinitionListOption ¶ added in v0.3.1

type DefinitionListOption func(*DefinitionList)

DefinitionListOption is a function that configures a DefinitionList

func WithDefinitionListStyles(styles DefinitionListStyles) DefinitionListOption

func WithDefinitionListTitle(title string) DefinitionListOption

type DefinitionListStyles ¶ added in v0.3.1

type DefinitionListStyles struct {
	Title       lipgloss.Style
	Term        lipgloss.Style
	Description lipgloss.Style
	DetailName  lipgloss.Style
	DetailType  lipgloss.Style
	Required    lipgloss.Style
	TreeLine    lipgloss.Style
}

DefinitionListStyles contains the styling configuration

func DefaultDefinitionListStyles() DefinitionListStyles

type Diagnostic ¶ added in v0.13.0

type Diagnostic struct {
	// Summary is the one-line headline: what failed, in the reader's terms.
	Summary string
	// Detail is prose explaining what was observed. Wrapped to terminal width.
	Detail string
	// Facts are label/value context pairs, rendered in an aligned column.
	Facts []Fact
	// Causes are possible explanations, most common first. This section only
	// appears when we genuinely don't know which one it is: a diagnosis we're
	// sure of states the cause outright in Detail instead.
	Causes []string
	// Actions are suggested next commands.
	Actions []Action
	// Cause is the underlying error. It is always reachable via errors.Unwrap
	// and included in Error(), but only displayed in the rich block when
	// ShowCause is set, since raw transport errors are noise for most readers.
	Cause error
	// ShowCause displays Cause in the rendered block (wire it to -v).
	ShowCause bool
}

Diagnostic is a structured, human-facing failure report. It implements TerminalError, so returning one from a command yields a rich block on a terminal while Error() stays a single line suitable for logs and wrapping.

Both renderers read the same fields, which is the point: a hand-written WriteForTerminal alongside a hand-written Error() drifts apart the first time someone edits one of them.

Only fill in what you actually know. Every section is omitted when empty, and per the doctor design rule, Causes should only list possibilities the reader can act on.

d := &Diagnostic{
	Summary: `couldn't reach cluster "prod" at cluster.example.com:8443`,
	Detail:  "Nothing answered after 5s. The hostname resolved, so either the server isn't running or something between here and there is blocking it.",
	Facts: []Fact{
		{Label: "Cluster", Value: "prod"},
		{Label: "Address", Value: "cluster.example.com:8443"},
	},
	Causes: []string{"the server isn't running", "a firewall is blocking UDP"},
	Actions: []Action{
		{Command: "miren doctor", Note: "check what's reachable"},
		{Command: "miren cluster list", Note: "see configured clusters"},
	},
}
d.WriteForTerminal(os.Stdout)

Output:
ERROR: couldn't reach cluster "prod" at cluster.example.com:8443

  Nothing answered after 5s. The hostname resolved, so either the server isn't
  running or something between here and there is blocking it.

  Cluster  prod
  Address  cluster.example.com:8443

  Possible causes
    • the server isn't running
    • a firewall is blocking UDP

  Try
    miren doctor          check what's reachable
    miren cluster list    see configured clusters

func (d *Diagnostic) Error() string

func (d *Diagnostic) Unwrap() error

func (d *Diagnostic) WriteForTerminal(w io.Writer)

func (d *Diagnostic) WriteWithSeverity(w io.Writer, sev Severity)

type Fact ¶ added in v0.13.0

type Fact struct {
	Label string
	Value string
}

Fact is a label/value pair shown in an aligned column, for context the reader needs but shouldn't have to parse out of prose (cluster, address, elapsed).

type Hint ¶ added in v0.3.1

type Hint struct {
	// contains filtered or unexported fields
}

Hint renders a dimmed hint/tip message

func NewHint(text string) *Hint

func (h *Hint) Render() string

func (h *Hint) WithStyle(style lipgloss.Style) *Hint

type List ¶

type List struct {
	// contains filtered or unexported fields
}

func NewList(w io.Writer) *List

type NamedValue ¶ added in v0.3.1

type NamedValue struct {
	Label     string
	Value     string
	ValueType ValueType
}

NamedValue represents a label-value pair for display

func NewNamedValue(label string, value any) NamedValue

type NamedValueList ¶ added in v0.3.1

type NamedValueList struct {
	// contains filtered or unexported fields
}

NamedValueList renders a list of named values with right-aligned labels

func NewNamedValueList(items []NamedValue, opts ...NamedValueOption) *NamedValueList

func (n *NamedValueList) Render() string

type NamedValueOption ¶ added in v0.3.1

type NamedValueOption func(*NamedValueList)

NamedValueOption is a function that configures a NamedValueList

func WithNamedValueStyles(styles NamedValueStyles) NamedValueOption

type NamedValueStyles ¶ added in v0.3.1

type NamedValueStyles struct {
	Label       lipgloss.Style
	Separator   string
	StringValue lipgloss.Style
	NumberValue lipgloss.Style
	BoolValue   lipgloss.Style
	NullValue   lipgloss.Style
	OtherValue  lipgloss.Style
}

NamedValueStyles contains the styling configuration for named values

func DefaultNamedValueStyles() NamedValueStyles

type PickerItem ¶

type PickerItem interface {
	// Row returns the table row data for this item
	Row() []string
	// ID returns a unique identifier for this item
	ID() string
}

PickerItem represents an item that can be selected in the picker

func RunPicker(items []PickerItem, opts ...PickerOption) (PickerItem, error)

type PickerModel ¶

type PickerModel struct {
	Title   string
	Headers []string
	Items   []PickerItem

	Selected  PickerItem
	Cancelled bool
	Footer    string

	// Optional filter function to disable certain items
	IsDisabled func(item PickerItem) bool
	// Optional message for disabled items
	DisabledMessage string
	// contains filtered or unexported fields
}

PickerModel is a table-based picker for selecting from a list of items

func NewPicker(items []PickerItem, opts ...PickerOption) *PickerModel

func (m *PickerModel) Init() tea.Cmd

func (m *PickerModel) SetCursor(index int)

func (m *PickerModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)

func (m *PickerModel) View() string

type PickerOption ¶

type PickerOption func(*PickerModel)

Picker configuration options

func WithDisabledCheck(check func(PickerItem) bool, message string) PickerOption

func WithFooter(footer string) PickerOption

func WithHeaders(headers []string) PickerOption

func WithTitle(title string) PickerOption

type PromptOption ¶

type PromptOption func(*promptConfig)

PromptOption configures a text input prompt

func WithCharLimit(limit int) PromptOption

func WithLabel(label string) PromptOption

func WithPlaceholder(placeholder string) PromptOption

func WithSensitive(sensitive bool) PromptOption

func WithWidth(width int) PromptOption

type Row ¶

type Row []string

Row represents a single row of data in the table

type Severity ¶ added in v0.13.0

type Severity int

Severity selects the label a Diagnostic leads with and the color it wears.

const (
	SeverityError Severity = iota
	SeverityWarning
)

type SeverityTerminalError ¶ added in v0.13.0

type SeverityTerminalError interface {
	TerminalError
	WriteWithSeverity(w io.Writer, sev Severity)
}

SeverityTerminalError is a TerminalError that renders its own severity label (an "ERROR:"/"WARNING:" prefix, colored to match). The display boundary must not add a prefix of its own to these, and should pass the severity it wants instead — the same error is an error in one place and a warning in another.

type SimplePickerItem ¶

type SimplePickerItem struct {
	Text   string
	Active bool
}

SimplePickerItem is a basic implementation of PickerItem for single-column pickers

func (s SimplePickerItem) ID() string

func (s SimplePickerItem) Row() []string

type Table ¶

type Table struct {
	// contains filtered or unexported fields
}

Table represents a simple, non-interactive table for CLI output

func NewTable(opts ...TableOption) *Table

func (t *Table) Render() string

type TableOption ¶

type TableOption func(*Table)

TableOption is a function that configures a table

func WithColumns(cols []Column) TableOption

func WithRows(rows []Row) TableOption

func WithStyles(styles TableStyles) TableOption

func WithTableTitle(title string) TableOption

type TablePickerItem ¶

type TablePickerItem struct {
	Columns []string
	ItemID  string
}

TablePickerItem is a multi-column implementation of PickerItem

func (t TablePickerItem) ID() string

func (t TablePickerItem) Row() []string

type TableStyles ¶

type TableStyles struct {
	Header lipgloss.Style
	Cell   lipgloss.Style
	Title  lipgloss.Style
}

TableStyles contains the styling configuration for the table

func DefaultTableStyles() TableStyles

type TerminalError ¶ added in v0.7.0

type TerminalError interface {
	error
	WriteForTerminal(w io.Writer)
}

TerminalError is an optional interface for errors that can render a rich, human-friendly representation to a terminal. Errors that implement this interface get colorized, multi-line output with source context when displayed through the CLI.

The Error() method should still return a plain-text representation suitable for logging and wrapping. WriteForTerminal provides the enhanced version for interactive use.

This follows the same pattern as io.WriterTo and http.Flusher — a type assertion at the display boundary unlocks richer behavior.

Design note: this interface is rendering-only. The underlying error type should carry structured data (source locations, hints, etc.) as exported fields so that the data can be serialized over RPC. Client-side code can then reconstruct a TerminalError from the wire data for local rendering.

type ValueType ¶ added in v0.3.1

type ValueType int

ValueType represents the type of a value for styling purposes

const (
	ValueTypeString ValueType = iota
	ValueTypeNumber
	ValueTypeBool
	ValueTypeNull
	ValueTypeOther
)