Select default emulator on first run

CLAUDE.md

@@ -96,7 +96,7 @@ Environment variables:
 - Reuse `FormatEventLine(event Event)` 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.
+- Domain packages (`internal/` minus `internal/ui/`) must not import Bubble Tea or UI packages. A useful test: domain code should work unchanged if `internal/ui/` were swapped for a different frontend.
 - 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.
@@ -118,9 +118,11 @@ Domain code must never read from stdin or wait for user input directly. Instead:
    - `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.
+3. The TUI (`internal/ui/app.go`) handles these events by showing the prompt and sending the response when the user interacts. `internal/ui/` is responsible only for the interaction itself — it does not contain the logic that acts on the response.
 
-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").
+4. The logic executed in response to the user's choice (e.g., writing config, starting a container) belongs in a domain package alongside the rest of the feature, not in `internal/ui/`.
+
+5. 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

cmd/aws.go

@@ -33,7 +33,7 @@ Examples:
   lstk aws sqs list-queues
   lstk aws s3 mb s3://my-bucket`,
 		DisableFlagParsing: true,
-		PreRunE:            initConfig,
+		PreRunE:            initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {

cmd/config.go

@@ -23,7 +23,7 @@ func newConfigProfileCmd(cfg *env.Env) *cobra.Command {
 	return &cobra.Command{
 		Use:     "profile",
 		Short:   "Deprecated: use 'lstk setup aws' instead",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appConfig, err := config.Get()
 			if err != nil {

cmd/login.go

@@ -18,7 +18,7 @@ func newLoginCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.
 		Use:     "login",
 		Short:   "Manage login",
 		Long:    "Manage login and store credentials in system keyring",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if !isInteractiveMode(cfg) {
 				return fmt.Errorf("login requires an interactive terminal")

cmd/logout.go

@@ -21,7 +21,7 @@ func newLogoutCmd(cfg *env.Env, logger log.Logger) *cobra.Command {
 	return &cobra.Command{
 		Use:     "logout",
 		Short:   "Remove stored authentication credentials",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			platformClient := api.NewPlatformClient(cfg.APIEndpoint, logger)
 			appConfig, err := config.Get()

cmd/logs.go

@@ -18,7 +18,7 @@ func newLogsCmd(cfg *env.Env) *cobra.Command {
 		Use:     "logs",
 		Short:   "Show emulator logs",
 		Long:    "Show logs from the emulator. Use --follow to stream in real-time.",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			follow, err := cmd.Flags().GetBool("follow")
 			if err != nil {

cmd/restart.go

@@ -20,7 +20,7 @@ func newRestartCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobr
 		Use:     "restart",
 		Short:   "Restart emulator",
 		Long:    "Stop and restart emulator and services.",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {

cmd/root.go

@@ -30,11 +30,12 @@ import (
 )
 
 func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.Command {
+	var firstRun bool
 	root := &cobra.Command{
 		Use:     "lstk",
 		Short:   "LocalStack CLI",
 		Long:    "lstk is the command-line interface for LocalStack.",
-		PreRunE: initConfig,
+		PreRunE: initConfig(&firstRun),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
@@ -44,7 +45,7 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 			if err != nil {
 				return err
 			}
-			return startEmulator(cmd.Context(), rt, cfg, tel, logger, persist)
+			return startEmulator(cmd.Context(), rt, cfg, tel, logger, persist, firstRun)
 		},
 	}
 
@@ -152,8 +153,7 @@ func buildStartOptions(cfg *env.Env, appConfig *config.Config, logger log.Logger
 	}
 }
 
-func startEmulator(ctx context.Context, rt runtime.Runtime, cfg *env.Env, tel *telemetry.Client, logger log.Logger, persist bool) error {
-
+func startEmulator(ctx context.Context, rt runtime.Runtime, cfg *env.Env, tel *telemetry.Client, logger log.Logger, persist bool, firstRun bool) error {
 	appConfig, err := config.Get()
 	if err != nil {
 		return fmt.Errorf("failed to get config: %w", err)
@@ -174,27 +174,25 @@ func startEmulator(ctx context.Context, rt runtime.Runtime, cfg *env.Env, tel *t
 	}
 
 	if isInteractiveMode(cfg) {
-		labelCh := make(chan string, 1)
-		go func() {
-			label, ok := container.ResolveEmulatorLabel(ctx, opts.PlatformClient, appConfig.Containers, cfg.AuthToken, logger)
-			if ok {
-				config.CachePlanLabel(label)
-			}
-			labelCh <- label
-		}()
-
 		return ui.Run(ctx, ui.RunOptions{
-			Runtime:       rt,
-			Version:       version.Version(),
-			StartOptions:  opts,
-			NotifyOptions: notifyOpts,
-			ConfigPath:    configPath,
-			EmulatorLabel: config.CachedPlanLabel(),
-			LabelCh:       labelCh,
+			Runtime:                rt,
+			Version:                version.Version(),
+			StartOptions:           opts,
+			NotifyOptions:          notifyOpts,
+			ConfigPath:             configPath,
+			EmulatorLabel:          config.CachedPlanLabel(),
+			NeedsEmulatorSelection: firstRun,
 		})
 	}
 
 	sink := output.NewPlainSink(os.Stdout)
+	if firstRun && len(appConfig.Containers) > 0 {
+		emName := appConfig.Containers[0].Type.ShortName()
+		sink.Emit(output.MessageEvent{
+			Severity: output.SeverityNote,
+			Text:     fmt.Sprintf("Configured with default emulator %s.", emName),
+		})
+	}
 	update.NotifyUpdate(ctx, sink, update.NotifyOptions{GitHubToken: cfg.GitHubToken})
 	return container.Start(ctx, rt, sink, opts, false)
 }
@@ -288,13 +286,19 @@ func newLogger() (log.Logger, func(), error) {
 	return log.New(f), func() { _ = f.Close() }, nil
 }
 
-func initConfig(cmd *cobra.Command, _ []string) error {
-	path, err := cmd.Flags().GetString("config")
-	if err != nil {
+func initConfig(firstRun *bool) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, _ []string) error {
+		path, err := cmd.Flags().GetString("config")
+		if err != nil {
+			return err
+		}
+		if path != "" {
+			return config.InitFromPath(path)
+		}
+		isFirstRun, err := config.Init()
+		if firstRun != nil {
+			*firstRun = isFirstRun
+		}
 		return err
 	}
-	if path != "" {
-		return config.InitFromPath(path)
-	}
-	return config.Init()
 }

cmd/setup.go

@@ -24,7 +24,7 @@ func newSetupAWSCmd(cfg *env.Env) *cobra.Command {
 		Use:     "aws",
 		Short:   "Set up the LocalStack AWS profile",
 		Long:    "Set up the LocalStack AWS profile in ~/.aws/config and ~/.aws/credentials for use with AWS CLI and SDKs.",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appConfig, err := config.Get()
 			if err != nil {

cmd/start.go

@@ -9,21 +9,22 @@ import (
 )
 
 func newStartCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.Command {
+	var firstRun bool
 	cmd := &cobra.Command{
 		Use:     "start",
 		Short:   "Start emulator",
 		Long:    "Start emulator and services.",
-		PreRunE: initConfig,
-		RunE: func(cmd *cobra.Command, args []string) error {
+		PreRunE: initConfig(&firstRun),
+		RunE: func(c *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
-			persist, err := cmd.Flags().GetBool("persist")
+			persist, err := c.Flags().GetBool("persist")
 			if err != nil {
 				return err
 			}
-			return startEmulator(cmd.Context(), rt, cfg, tel, logger, persist)
+			return startEmulator(c.Context(), rt, cfg, tel, logger, persist, firstRun)
 		},
 	}
 	cmd.Flags().Bool("persist", false, "Enable local persistence (sets LOCALSTACK_PERSISTENCE=1)")

cmd/status.go

@@ -21,7 +21,7 @@ func newStatusCmd(cfg *env.Env) *cobra.Command {
 		Use:     "status",
 		Short:   "Show emulator status and deployed resources",
 		Long:    "Show the status of a running emulator and its deployed resources",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {

cmd/stop.go

@@ -19,7 +19,7 @@ func newStopCmd(cfg *env.Env, tel *telemetry.Client) *cobra.Command {
 		Use:     "stop",
 		Short:   "Stop emulator",
 		Long:    "Stop emulator and services",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {

cmd/update.go

@@ -17,7 +17,7 @@ func newUpdateCmd(cfg *env.Env) *cobra.Command {
 		Use:     "update",
 		Short:   "Update lstk to the latest version",
 		Long:    "Check for and apply updates to the lstk CLI. Respects the original installation method (Homebrew, npm, or direct binary).",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if isInteractiveMode(cfg) {
 				return ui.RunUpdate(cmd.Context(), checkOnly, cfg.GitHubToken)

cmd/volume.go

@@ -26,7 +26,7 @@ func newVolumePathCmd(cfg *env.Env) *cobra.Command {
 	return &cobra.Command{
 		Use:     "path",
 		Short:   "Print the volume directory path",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appConfig, err := config.Get()
 			if err != nil {
@@ -56,7 +56,7 @@ func newVolumeClearCmd(cfg *env.Env) *cobra.Command {
 		Use:     "clear",
 		Short:   "Clear emulator volume data",
 		Long:    "Remove all data from the emulator volume directory. This resets cached state such as certificates, downloaded tools, and persistence data.",
-		PreRunE: initConfig,
+		PreRunE: initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appConfig, err := config.Get()
 			if err != nil {

internal/config/config.go

@@ -52,15 +52,17 @@ func InitFromPath(path string) error {
 	return loadConfig(path)
 }
 
-func Init() error {
+// Init loads the config file, searching the standard paths. If no config file
+// exists, it creates one from the default template and returns firstRun=true.
+func Init() (firstRun bool, err error) {
 	viper.Reset()
 	setDefaults()
 	viper.SetConfigName(configName)
 	viper.SetConfigType(configType)
 
 	dirs, err := configSearchDirs()
 	if err != nil {
-		return err
+		return false, err
 	}
 	for _, dir := range dirs {
 		viper.AddConfigPath(dir)
@@ -70,43 +72,43 @@ func Init() error {
 		var notFoundErr viper.ConfigFileNotFoundError
 		if !errors.As(err, &notFoundErr) {
 			if used := viper.ConfigFileUsed(); filepath.Ext(used) == ".yaml" || filepath.Ext(used) == ".yml" {
-				return fmt.Errorf("%s is from an old lstk version; lstk now uses TOML format — remove it or replace it with a config.toml file", used)
+				return false, fmt.Errorf("%s is from an old lstk version; lstk now uses TOML format — remove it or replace it with a config.toml file", used)
 			}
-			return fmt.Errorf("failed to read config file: %w", err)
+			return false, fmt.Errorf("failed to read config file: %w", err)
 		}
 
 		// No config found anywhere, create one using creation policy.
 		creationDir, err := configCreationDir()
 		if err != nil {
-			return err
+			return false, err
 		}
 
 		if err := os.MkdirAll(creationDir, 0755); err != nil {
-			return fmt.Errorf("failed to create config directory: %w", err)
+			return false, fmt.Errorf("failed to create config directory: %w", err)
 		}
 
 		configPath := filepath.Join(creationDir, configFileName)
 		f, err := os.OpenFile(configPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
 		if err != nil {
 			if errors.Is(err, os.ErrExist) {
-				return loadConfig(configPath)
+				return false, loadConfig(configPath)
 			}
-			return fmt.Errorf("failed to create config file: %w", err)
+			return false, fmt.Errorf("failed to create config file: %w", err)
 		}
 		_, writeErr := f.WriteString(defaultConfigTemplate)
 		closeErr := f.Close()
 		if writeErr != nil {
 			_ = os.Remove(configPath)
-			return fmt.Errorf("failed to write config file: %w", writeErr)
+			return false, fmt.Errorf("failed to write config file: %w", writeErr)
 		}
 		if closeErr != nil {
 			_ = os.Remove(configPath)
-			return fmt.Errorf("failed to close config file: %w", closeErr)
+			return false, fmt.Errorf("failed to close config file: %w", closeErr)
 		}
 
-		return loadConfig(configPath)
+		return true, loadConfig(configPath)
 	}
-	return nil
+	return false, nil
 }
 
 func resolvedConfigPath() string {

internal/config/containers.go

@@ -25,6 +25,24 @@ var emulatorDisplayNames = map[EmulatorType]string{
 	EmulatorAzure:     "Azure",
 }
 
+// SelectableEmulatorTypes lists the emulator types available for interactive selection,
+// in the order they should be presented. The selection key for each type is its first character.
+var SelectableEmulatorTypes = []EmulatorType{EmulatorAWS, EmulatorSnowflake}
+
+func (e EmulatorType) SelectionKey() string {
+	return string(e)[0:1]
+}
+
+func (e EmulatorType) ShortName() string {
+	if name, ok := emulatorDisplayNames[e]; ok {
+		return name
+	}
+	return string(e)
+}
+
+func (e EmulatorType) DisplayName() string {
+	return fmt.Sprintf("LocalStack %s Emulator", e.ShortName())
+}
 var emulatorHealthPaths = map[EmulatorType]string{
 	EmulatorAWS:       "/_localstack/health",
 	EmulatorSnowflake: "/_localstack/health",
@@ -68,13 +86,6 @@ func KnownImageReposForType(t EmulatorType) []string {
 	return repos
 }
 
-func DisplayNameForType(t EmulatorType) string {
-	name, ok := emulatorDisplayNames[t]
-	if !ok {
-		return fmt.Sprintf("LocalStack %s Emulator", t)
-	}
-	return fmt.Sprintf("LocalStack %s Emulator", name)
-}
 
 type ContainerConfig struct {
 	Type   EmulatorType `mapstructure:"type"`
@@ -168,7 +179,7 @@ func (c *ContainerConfig) ContainerPort() (string, error) {
 }
 
 func (c *ContainerConfig) DisplayName() string {
-	return DisplayNameForType(c.Type)
+	return c.Type.DisplayName()
 }
 
 func (c *ContainerConfig) ProductName() (string, error) {