Add TUI architecture with a header

CLAUDE.md

@@ -26,6 +26,7 @@ Note: Integration tests require `LOCALSTACK_AUTH_TOKEN` environment variable for
   - `runtime/` - Abstraction for container runtimes (Docker, Kubernetes, etc.) - currently only Docker implemented
   - `auth/` - Authentication (env var token or browser-based login)
   - `output/` - Generic event and sink abstractions for CLI/TUI/non-interactive rendering
+  - `ui/` - Bubble Tea views for interactive output
 
 # Configuration
 
@@ -47,13 +48,81 @@ Environment variables:
 # Testing
 
 - Prefer integration tests to cover most cases. Use unit tests when integration tests are not practical.
+- Integration tests that run the CLI binary with Bubble Tea must use a PTY (`github.com/creack/pty`) since Bubble Tea requires a terminal. Use `pty.Start(cmd)` instead of `cmd.CombinedOutput()`, read output with `io.Copy()`, and send keystrokes by writing to the PTY (e.g., `ptmx.Write([]byte("\r"))` for Enter).
+
+# Output Routing and Events
+
+- Emit typed events through `internal/output` (`EmitLog`, `EmitStatus`, `EmitProgress`, etc.) instead of printing from domain/command handlers.
+- Keep `output.Sink` sealed (unexported `emit`); sink implementations belong in `internal/output`.
+- Reuse `FormatEventLine(event any)` for all line-oriented rendering so plain and TUI output stay consistent.
+- Select output mode at the command boundary in `cmd/`: interactive TTY runs Bubble Tea, non-interactive mode uses `output.NewPlainSink(...)`.
+- Keep non-TTY mode non-interactive (no stdin prompts or input waits).
+- Domain packages must not import Bubble Tea or UI packages.
+- Any feature/workflow package that produces user-visible progress should accept an `output.Sink` dependency and emit events through `internal/output`.
+- Do not pass UI callbacks like `onProgress func(...)` through domain layers; prefer typed output events.
+- Event payloads should be domain facts (phase/status/progress), not pre-rendered UI strings.
+- When adding a new event type, update all of:
+  - `internal/output/events.go` (event type + union + emit helper)
+  - `internal/output/format.go` (line formatting fallback)
+  - tests in `internal/output/*_test.go` for formatter/sink behavior parity
+
+## User Input Handling
+
+Domain code must never read from stdin or wait for user input directly. Instead:
+
+1. Emit a `UserInputRequestEvent` via `output.EmitUserInputRequest()` with:
+   - `Prompt`: message to display
+   - `Options`: available choices (e.g., `{Key: "enter", Label: "Press ENTER to continue"}`)
+   - `ResponseCh`: channel to receive the user's response
+
+2. Wait on the `ResponseCh` for an `InputResponse` containing:
+   - `SelectedKey`: which option was selected
+   - `Cancelled`: true if user cancelled (e.g., Ctrl+C)
+
+3. The TUI (`internal/ui/app.go`) handles these events by showing the prompt and sending the response when the user interacts.
+
+4. In non-interactive mode, commands requiring user input should fail early with a helpful error (e.g., "set LOCALSTACK_AUTH_TOKEN or run in interactive mode").
+
+Example flow in auth login:
+```go
+responseCh := make(chan output.InputResponse, 1)
+output.EmitUserInputRequest(sink, output.UserInputRequestEvent{
+    Prompt:     "Waiting for authentication...",
+    Options:    []output.InputOption{{Key: "enter", Label: "Press ENTER when complete"}},
+    ResponseCh: responseCh,
+})
+
+select {
+case resp := <-responseCh:
+    if resp.Cancelled {
+        return "", context.Canceled
+    }
+    // proceed with user's choice
+case <-ctx.Done():
+    return "", ctx.Err()
+}
+```
 
-# Output Routing
-
-- Emit progress/events through `internal/output` sinks instead of printing directly from command handlers.
-- Use `output.NewPlainSink(...)` for CLI text output.
-- Prefer typed `output.Sink` dependencies over raw callback functions like `func(string)`.
-- Keep reusable output primitives in `internal/output`; command-specific orchestration can live in `cmd/`.
+# UI Development (Bubble Tea TUI)
+
+## Structure
+- `internal/ui/` - Bubble Tea app model and run orchestration
+- `internal/ui/components/` - Reusable presentational components
+- `internal/ui/styles/` - Lipgloss style definitions and palette constants
+
+## Component and Model Rules
+1. Keep components small and focused (single concern each).
+2. Keep UI as presentation/orchestration only; business logic stays in domain packages.
+3. Long-running work must run outside `Update()` (goroutine or command path), with UI updates sent asynchronously.
+4. Bubble Tea updates from background work should flow through `Program.Send()` via `output.NewTUISink(...)`.
+5. `Update()` must stay non-blocking.
+6. UI should consume shared output events directly; add UI-only wrapper/control messages only when needed, and suffix them with `...Msg`.
+7. Keep message/history state bounded (for example, capped line buffer).
+
+## Styling Rules
+- Define styles with semantic names in `internal/ui/styles/styles.go`.
+- Preserve the Nimbo palette constants (`#3F51C7`, `#5E6AD2`, `#7E88EC`) unless intentionally changing branding.
+- If changing palette constants, update/add tests to guard against accidental drift.
 
 # Maintaining This File
 

cmd/login.go

@@ -2,11 +2,9 @@ package cmd
 
 import (
 	"fmt"
-	"os"
 
 	"github.com/localstack/lstk/internal/api"
-	"github.com/localstack/lstk/internal/auth"
-	"github.com/localstack/lstk/internal/output"
+	"github.com/localstack/lstk/internal/ui"
 	"github.com/spf13/cobra"
 )
 
@@ -15,19 +13,11 @@ var loginCmd = &cobra.Command{
 	Short: "Authenticate with LocalStack",
 	Long:  "Authenticate with LocalStack and store credentials in system keyring",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		sink := output.NewPlainSink(os.Stdout)
-		platformClient := api.NewPlatformClient()
-		a, err := auth.New(sink, platformClient)
-		if err != nil {
-			return fmt.Errorf("failed to initialize auth: %w", err)
-		}
-
-		_, err = a.GetToken(cmd.Context())
-		if err != nil {
-			return err
+		if !ui.IsInteractive() {
+			return fmt.Errorf("login requires an interactive terminal")
 		}
-
-		return nil
+		platformClient := api.NewPlatformClient()
+		return ui.RunLogin(cmd.Context(), version, platformClient)
 	},
 }
 

cmd/logout.go

@@ -16,10 +16,11 @@ var logoutCmd = &cobra.Command{
 	RunE: func(cmd *cobra.Command, args []string) error {
 		sink := output.NewPlainSink(os.Stdout)
 		platformClient := api.NewPlatformClient()
-		a, err := auth.New(sink, platformClient)
+		tokenStorage, err := auth.NewTokenStorage()
 		if err != nil {
-			return fmt.Errorf("failed to initialize auth: %w", err)
+			return fmt.Errorf("failed to initialize token storage: %w", err)
 		}
+		a := auth.New(sink, platformClient, tokenStorage, false)
 		if err := a.Logout(); err != nil {
 			return fmt.Errorf("failed to logout: %w", err)
 		}

cmd/root.go

@@ -10,6 +10,7 @@ import (
 	"github.com/localstack/lstk/internal/container"
 	"github.com/localstack/lstk/internal/output"
 	"github.com/localstack/lstk/internal/runtime"
+	"github.com/localstack/lstk/internal/ui"
 	"github.com/spf13/cobra"
 )
 
@@ -53,5 +54,9 @@ func Execute(ctx context.Context) error {
 }
 
 func runStart(ctx context.Context, rt runtime.Runtime) error {
-	return container.Start(ctx, rt, output.NewPlainSink(os.Stdout), api.NewPlatformClient())
+	platformClient := api.NewPlatformClient()
+	if ui.IsInteractive() {
+		return ui.Run(ctx, rt, version, platformClient)
+	}
+	return container.Start(ctx, rt, output.NewPlainSink(os.Stdout), platformClient, false)
 }

go.mod

@@ -4,62 +4,84 @@ go 1.26.0
 
 require (
 	github.com/99designs/keyring v1.2.2
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/charmbracelet/x/exp/teatest v0.0.0-20260216111343-536eb63c1f4c
 	github.com/containerd/errdefs v1.0.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.6.0
+	github.com/muesli/termenv v0.16.0
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	go.uber.org/mock v0.6.0
+	golang.org/x/term v0.40.0
+	gotest.tools/v3 v3.5.2
 )
 
 require (
 	github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 // indirect
-	github.com/Microsoft/go-winio v0.4.21 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	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/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/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.10.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.6.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/containerd/log v0.1.0 // indirect
-	github.com/danieljoos/wincred v1.2.2 // indirect
+	github.com/danieljoos/wincred v1.2.3 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
-	github.com/dvsekhvalnov/jose2go v1.5.0 // indirect
+	github.com/dvsekhvalnov/jose2go v1.8.0 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
-	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.19 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/sys/atomicwriter v0.1.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
 	github.com/morikuni/aec v1.1.0 // indirect
 	github.com/mtibben/percent v0.2.1 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/sagikazarmark/locafero v0.11.0 // indirect
-	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0 // indirect
-	go.opentelemetry.io/otel v1.39.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
+	go.opentelemetry.io/otel v1.40.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.39.0 // indirect
-	go.opentelemetry.io/otel/metric v1.39.0 // indirect
-	go.opentelemetry.io/otel/trace v1.39.0 // indirect
+	go.opentelemetry.io/otel/metric v1.40.0 // indirect
+	go.opentelemetry.io/otel/trace v1.40.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/sys v0.39.0 // indirect
-	golang.org/x/term v0.3.0 // indirect
-	golang.org/x/text v0.31.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	gotest.tools/v3 v3.5.2 // indirect
 )