Improve event system structure and add reusable TUI components

go.mod

@@ -26,10 +26,11 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymanbagabas/go-udiff v0.3.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charmbracelet/bubbles v1.0.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.2 // indirect
 	github.com/charmbracelet/x/ansi v0.11.6 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a // indirect
+	github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91 // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.10.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.6.0 // indirect

go.sum

@@ -14,6 +14,8 @@ github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1x
 github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/charmbracelet/bubbles v1.0.0 h1:12J8/ak/uCZEMQ6KU7pcfwceyjLlWsDLAxB5fXonfvc=
+github.com/charmbracelet/bubbles v1.0.0/go.mod h1:9d/Zd5GdnauMI5ivUIVisuEm3ave1XwXtD1ckyV6r3E=
 github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
 github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
 github.com/charmbracelet/colorprofile v0.4.2 h1:BdSNuMjRbotnxHSfxy+PCSa4xAmz7szw70ktAtWRYrY=
@@ -26,6 +28,8 @@ github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMx
 github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a h1:G99klV19u0QnhiizODirwVksQB91TJKV/UaTnACcG30=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240806155701-69247e0abc2a/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
+github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91 h1:payRxjMjKgx2PaCWLZ4p3ro9y97+TVLZNaRZgJwSVDQ=
+github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
 github.com/charmbracelet/x/exp/teatest v0.0.0-20260216111343-536eb63c1f4c h1:/pbU92+xMwttewB4XK69/B9ISH0HMhOMrTIVhV4AS7M=
 github.com/charmbracelet/x/exp/teatest v0.0.0-20260216111343-536eb63c1f4c/go.mod h1:aPVjFrBwbJgj5Qz1F0IXsnbcOVJcMKgu1ySUfTAxh7k=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=

internal/auth/auth.go

@@ -41,7 +41,7 @@ func (a *Auth) GetToken(ctx context.Context) (string, error) {
 		return "", fmt.Errorf("authentication required: set LOCALSTACK_AUTH_TOKEN or run in interactive mode")
 	}
 
-	output.EmitLog(a.sink, "No existing credentials found. Please log in:")
+	output.EmitInfo(a.sink, "No existing credentials found. Please log in:")
 	token, err := a.login.Login(ctx)
 	if err != nil {
 		output.EmitWarning(a.sink, "Authentication failed.")
@@ -52,7 +52,7 @@ func (a *Auth) GetToken(ctx context.Context) (string, error) {
 		output.EmitWarning(a.sink, fmt.Sprintf("could not store token in keyring: %v", err))
 	}
 
-	output.EmitLog(a.sink, "Login successful.")
+	output.EmitSuccess(a.sink, "Login successful.")
 	return token, nil
 }
 

internal/auth/auth_test.go

@@ -49,8 +49,8 @@ func TestGetToken_ReturnsTokenWhenKeyringStoreFails(t *testing.T) {
 	assert.Equal(t, "test-token", token)
 	assert.Condition(t, func() bool {
 		for _, event := range events {
-			warningEvent, ok := event.(output.WarningEvent)
-			if ok && strings.Contains(warningEvent.Message, "could not store token in keyring") {
+			msgEvent, ok := event.(output.MessageEvent)
+			if ok && msgEvent.Severity == output.SeverityWarning && strings.Contains(msgEvent.Text, "could not store token in keyring") {
 				return true
 			}
 		}

internal/auth/login.go

@@ -35,8 +35,8 @@ func (l *loginProvider) Login(ctx context.Context) (string, error) {
 	}
 
 	authURL := fmt.Sprintf("%s/auth/request/%s", getWebAppURL(), authReq.ID)
-	output.EmitLog(l.sink, fmt.Sprintf("Visit: %s", authURL))
-	output.EmitLog(l.sink, fmt.Sprintf("Verification code: %s", authReq.Code))
+	output.EmitInfo(l.sink, fmt.Sprintf("Visit: %s", authURL))
+	output.EmitInfo(l.sink, fmt.Sprintf("Verification code: %s", authReq.Code))
 
 	// Ask whether to open the browser; ENTER or Y accepts (default yes), N skips
 	browserCh := make(chan output.InputResponse, 1)
@@ -53,7 +53,7 @@ func (l *loginProvider) Login(ctx context.Context) (string, error) {
 		}
 		if resp.SelectedKey != "n" {
 			if err := browser.OpenURL(authURL); err != nil {
-				output.EmitLog(l.sink, fmt.Sprintf("Warning: Failed to open browser: %v", err))
+				output.EmitWarning(l.sink, fmt.Sprintf("Failed to open browser: %v", err))
 			}
 		}
 	case <-ctx.Done():
@@ -84,22 +84,22 @@ func getWebAppURL() string {
 }
 
 func (l *loginProvider) completeAuth(ctx context.Context, authReq *api.AuthRequest) (string, error) {
-	output.EmitLog(l.sink, "Checking if auth request is confirmed...")
+	output.EmitInfo(l.sink, "Checking if auth request is confirmed...")
 	confirmed, err := l.platformClient.CheckAuthRequestConfirmed(ctx, authReq.ID, authReq.ExchangeToken)
 	if err != nil {
 		return "", fmt.Errorf("failed to check auth request: %w", err)
 	}
 	if !confirmed {
 		return "", fmt.Errorf("auth request not confirmed - please complete the authentication in your browser")
 	}
-	output.EmitLog(l.sink, "Auth request confirmed, exchanging for token...")
+	output.EmitInfo(l.sink, "Auth request confirmed, exchanging for token...")
 
 	bearerToken, err := l.platformClient.ExchangeAuthRequest(ctx, authReq.ID, authReq.ExchangeToken)
 	if err != nil {
 		return "", fmt.Errorf("failed to exchange auth request: %w", err)
 	}
 
-	output.EmitLog(l.sink, "Fetching license token...")
+	output.EmitInfo(l.sink, "Fetching license token...")
 	licenseToken, err := l.platformClient.GetLicenseToken(ctx, bearerToken)
 	if err != nil {
 		return "", fmt.Errorf("failed to get license token: %w", err)

internal/container/start.go

@@ -139,7 +139,7 @@ func selectContainersToStart(ctx context.Context, rt runtime.Runtime, sink outpu
 			return nil, fmt.Errorf("failed to check container status: %w", err)
 		}
 		if running {
-			output.EmitLog(sink, fmt.Sprintf("%s is already running", c.Name))
+			output.EmitInfo(sink, fmt.Sprintf("%s is already running", c.Name))
 			continue
 		}
 		if err := ports.CheckAvailable(c.Port); err != nil {

internal/output/events.go

@@ -1,7 +1,53 @@
+// Package output defines events for the event/sink system
+//
+// MessageEvent (use via EmitInfo, EmitSuccess, EmitNote, EmitWarning):
+//   - SeverityInfo: Transient status ("Connecting...", "Validating...")
+//   - SeveritySuccess: Positive outcome ("Login successful")
+//   - SeverityNote: Informational outcome ("Not currently logged in")
+//   - SeverityWarning: Cautionary message ("Token expires soon")
+//
+// SpinnerEvent (use via EmitSpinnerStart, EmitSpinnerStop):
+//   - Show loading indicator during async operations
+//   - Always pair Start with Stop
+//
+// ErrorEvent (use via EmitError):
+//   - Structured errors with title, summary, detail, and recovery actions
+//   - Use for errors that need more than a single line
 package output
 
+type MessageSeverity int
+
+const (
+	SeverityInfo MessageSeverity = iota
+	SeveritySuccess
+	SeverityNote
+	SeverityWarning
+)
+
+type MessageEvent struct {
+	Severity MessageSeverity
+	Text     string
+}
+
+type SpinnerEvent struct {
+	Active bool
+	Text   string
+}
+
+type ErrorAction struct {
+	Label string
+	Value string
+}
+
+type ErrorEvent struct {
+	Title   string
+	Summary string
+	Detail  string
+	Actions []ErrorAction
+}
+
 type Event interface {
-	LogEvent | WarningEvent | ContainerStatusEvent | ProgressEvent | UserInputRequestEvent | ContainerLogLineEvent
+	MessageEvent | SpinnerEvent | ErrorEvent | ContainerStatusEvent | ProgressEvent | UserInputRequestEvent | ContainerLogLineEvent
 }
 
 type Sink interface {
@@ -18,14 +64,6 @@ func (f SinkFunc) emit(event any) {
 	f(event)
 }
 
-type LogEvent struct {
-	Message string
-}
-
-type WarningEvent struct {
-	Message string
-}
-
 type ContainerStatusEvent struct {
 	Phase     string // e.g., "pulling", "starting", "waiting", "ready"
 	Container string
@@ -68,12 +106,20 @@ func Emit[E Event](sink Sink, event E) {
 	sink.emit(event)
 }
 
-func EmitLog(sink Sink, message string) {
-	Emit(sink, LogEvent{Message: message})
+func EmitInfo(sink Sink, text string) {
+	Emit(sink, MessageEvent{Severity: SeverityInfo, Text: text})
+}
+
+func EmitSuccess(sink Sink, text string) {
+	Emit(sink, MessageEvent{Severity: SeveritySuccess, Text: text})
+}
+
+func EmitNote(sink Sink, text string) {
+	Emit(sink, MessageEvent{Severity: SeverityNote, Text: text})
 }
 
 func EmitWarning(sink Sink, message string) {
-	Emit(sink, WarningEvent{Message: message})
+	Emit(sink, MessageEvent{Severity: SeverityWarning, Text: message})
 }
 
 func EmitStatus(sink Sink, phase, container, detail string) {
@@ -97,3 +143,15 @@ func EmitUserInputRequest(sink Sink, event UserInputRequestEvent) {
 func EmitContainerLogLine(sink Sink, line string) {
 	Emit(sink, ContainerLogLineEvent{Line: line})
 }
+
+func EmitSpinnerStart(sink Sink, text string) {
+	Emit(sink, SpinnerEvent{Active: true, Text: text})
+}
+
+func EmitSpinnerStop(sink Sink) {
+	Emit(sink, SpinnerEvent{Active: false})
+}
+
+func EmitError(sink Sink, event ErrorEvent) {
+	Emit(sink, event)
+}

internal/output/format.go → internal/output/plain_format.go

@@ -8,10 +8,15 @@ import (
 // FormatEventLine converts an output event into a single display line.
 func FormatEventLine(event any) (string, bool) {
 	switch e := event.(type) {
-	case LogEvent:
-		return e.Message, true
-	case WarningEvent:
-		return fmt.Sprintf("Warning: %s", e.Message), true
+	case MessageEvent:
+		return formatMessageEvent(e), true
+	case SpinnerEvent:
+		if e.Active {
+			return e.Text + "...", true
+		}
+		return "", false
+	case ErrorEvent:
+		return formatErrorEvent(e), true
 	case ContainerStatusEvent:
 		return formatStatusLine(e), true
 	case ProgressEvent:
@@ -71,3 +76,37 @@ func formatUserInputRequest(e UserInputRequestEvent) string {
 		return fmt.Sprintf("%s [%s]", e.Prompt, strings.Join(labels, "/"))
 	}
 }
+
+func formatMessageEvent(e MessageEvent) string {
+	switch e.Severity {
+	case SeveritySuccess:
+		return "> Success: " + e.Text
+	case SeverityNote:
+		return "> Note: " + e.Text
+	case SeverityWarning:
+		return "> Warning: " + e.Text
+	default:
+		return e.Text
+	}
+}
+
+func formatErrorEvent(e ErrorEvent) string {
+	var sb strings.Builder
+	sb.WriteString("Error: ")
+	sb.WriteString(e.Title)
+	if e.Summary != "" {
+		sb.WriteString("\n  ")
+		sb.WriteString(e.Summary)
+	}
+	if e.Detail != "" {
+		sb.WriteString("\n  ")
+		sb.WriteString(e.Detail)
+	}
+	for _, action := range e.Actions {
+		sb.WriteString("\n  → ")
+		sb.WriteString(action.Label)
+		sb.WriteString(" ")
+		sb.WriteString(action.Value)
+	}
+	return sb.String()
+}