ux

Documentation

Overview

Package ux provides user-experience primitives for structured CLI error display. It wraps the errs.CLIError type with richer terminal rendering.

Index

• type UXError
  • func FromCLIError(e *errs.CLIError) *UXError
  • func New(code, what string) *UXError
  • func Newf(code, format string, args ...interface{}) *UXError
  • func Wrap(code, what string, err error) *UXError
  • func (e *UXError) Error() string
  • func (e *UXError) Print()
  • func (e *UXError) PrintAndReturn() error
  • func (e *UXError) Unwrap() error
  • func (e *UXError) WithSuggestions(suggestions ...string) *UXError
  • func (e *UXError) WithWhy(why string) *UXError

Types

type UXError

type UXError struct {
	// Code is the short error code (e.g. "E001").
	Code string
	// What is a plain-language description of what happened.
	What string
	// Why is the root cause.
	Why string
	// Suggestions is a list of actionable fix steps shown as a numbered list.
	Suggestions []string
	// DocsLink is the full URL to the error reference page.
	DocsLink string
	// Wrapped is an optional underlying error for errors.Is/As.
	Wrapped error
}

UXError is the display layer for a CLIError. It holds a structured error and renders it with colored terminal output, including what/why/suggestions/docs-link/error-code sections.

func FromCLIError

func FromCLIError(e *errs.CLIError) *UXError

FromCLIError converts an errs.CLIError to a UXError for rendering.

func New

func New(code, what string) *UXError

New creates a UXError from the error registry. Falls back to a generic error when the code is not registered.

func Newf

func Newf(code, format string, args ...interface{}) *UXError

Newf creates a UXError with a formatted What message.

func Wrap

func Wrap(code, what string, err error) *UXError

Wrap creates a UXError that wraps an underlying error.

func (*UXError) Error

func (e *UXError) Error() string

Error implements the error interface.

func (*UXError) Print

func (e *UXError) Print()

Print renders the UXError to stderr with ANSI formatting.

func (*UXError) PrintAndReturn

func (e *UXError) PrintAndReturn() error

PrintAndReturn prints the error to stderr and returns it as a plain error, so call sites can write: return ux.Newf("E001", "...").WithWhy("...").PrintAndReturn()

func (*UXError) Unwrap

func (e *UXError) Unwrap() error

Unwrap returns the wrapped error for errors.Is/As support.

func (*UXError) WithSuggestions

func (e *UXError) WithSuggestions(suggestions ...string) *UXError

WithSuggestions returns a copy of the error with additional suggestions.

func (*UXError) WithWhy

func (e *UXError) WithWhy(why string) *UXError

WithWhy returns a copy of the error with a custom Why field.