output

type AuthCompleteEvent ¶ added in v0.7.0

type AuthCompleteEvent struct{}

type AuthEvent ¶ added in v0.2.0

type AuthEvent struct {
	Preamble string
	Code     string
	URL      string
}

type ConfirmDefault ¶ added in v0.22.1

type ConfirmDefault int

ConfirmDefault selects which answer ENTER picks in a Confirm prompt. It is conveyed to the user by capitalizing that answer's label, which is also how the TUI's key resolution finds it — so the displayed default and the honored default cannot drift apart.

const (
	DefaultYes ConfirmDefault = iota
	DefaultNo
)

type ContainerStatusEvent ¶

type ContainerStatusEvent struct {
	Phase     string // e.g., "pulling", "starting", "waiting", "ready"
	Container string
	Detail    string // optional extra info (e.g., container ID)
}

type DeferredEvent ¶ added in v0.13.0

type DeferredEvent struct {
	Inner Event
}

DeferredEvent wraps another event so that the TUI renders it after the interface exits rather than inline. Plain sinks format the inner event immediately.

type EmulatorResetEvent ¶ added in v0.17.0

type EmulatorResetEvent struct {
	Type string
	Name string
}

EmulatorResetEvent reports that the named emulator's in-memory state was reset.

type EmulatorStartedEvent ¶ added in v0.23.0

type EmulatorStartedEvent struct {
	Type           string
	Container      string
	Endpoint       string
	Version        string
	AlreadyRunning bool
	Persistence    bool
}

EmulatorStartedEvent reports the emulator is up and reachable, whether freshly started or already running. JSON-only: no plain-text line, since start's existing messages already cover that.

type EmulatorStatusEvent ¶ added in v0.23.0

type EmulatorStatusEvent struct {
	Type          string
	Running       bool
	Health        string
	Name          string
	Version       string
	Host          string
	UptimeSeconds int64
	Persistence   bool
	// Local is true for a Docker-managed emulator, false for an external
	// --endpoint-url target. Name/UptimeSeconds/Persistence only apply to Local.
	Local     bool
	Resources []EmulatorStatusResource
}

EmulatorStatusEvent reports one running emulator's health state.

type EmulatorStatusResource ¶ added in v0.23.0

type EmulatorStatusResource struct {
	Service string
	Name    string
	Region  string
	Account string
}

EmulatorStatusResource mirrors emulator.Resource, kept local to avoid internal/output importing internal/emulator.

type EmulatorStoppedEvent ¶ added in v0.17.0

type EmulatorStoppedEvent struct {
	Type        string
	Name        string
	DisplayName string
	WasRunning  bool
}

EmulatorStoppedEvent reports that a configured emulator was running and has been stopped. WasRunning is always true today (Stop returns an error before reaching this point otherwise) but is carried explicitly for JSON shape stability. DisplayName is precomputed by the caller (e.g. "LocalStack AWS Emulator"), matching InstanceInfoEvent.EmulatorName's existing precedent, so internal/output never needs to know how to derive it from Type.

type Envelope ¶ added in v0.17.0

type Envelope struct {
	SchemaVersion int            `json:"schemaVersion"`
	Command       string         `json:"command"`
	Status        string         `json:"status"`
	Data          any            `json:"data"`
	Warnings      []Warning      `json:"warnings"`
	Error         *EnvelopeError `json:"error"`
}

Envelope is the common result shape every JSON-capable command emits as a single object to stdout. Data and Warnings are always non-nil; Error is nil exactly when Status is "ok".

type EnvelopeAction ¶ added in v0.17.0

type EnvelopeAction struct {
	ID      string `json:"id"`
	Command string `json:"command"`
}

EnvelopeAction is a suggested remediation for an EnvelopeError. ID is a stable slug a script can switch on; Command is the literal shell command a human or script could run.

type EnvelopeError ¶ added in v0.17.0

type EnvelopeError struct {
	Code      ErrorCode        `json:"code"`
	Category  ErrorCategory    `json:"category"`
	Message   string           `json:"message"`
	Retryable bool             `json:"retryable"`
	Details   map[string]any   `json:"details,omitempty"`
	Actions   []EnvelopeAction `json:"actions,omitempty"`
}

EnvelopeError is the machine-readable error shape carried by a failed Envelope. Code is one of the constants in error_code.go and remains the primary, stable identifier; Category is an additive, coarse grouping of Code (~7 values vs. Code's ~28) for callers that only want to distinguish broad kinds of failure. Both Retryable and Category are static classifications of Code, never computed per instance.

type EnvelopeSink ¶ added in v0.17.0

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

EnvelopeSink implements Sink by accumulating events into an Envelope instead of formatting lines. This accumulation step is not JSON-specific — it would be identical for any structured serialization; only the final marshal (driven by Format) differs. Presentational events (SpinnerEvent, ContainerStatusEvent, ProgressEvent, UserInputRequestEvent, ...) have no place in a single terminal result and are silently dropped.

func NewEnvelopeSink(format Format) *EnvelopeSink

func (s *EnvelopeSink) Emit(event Event)

func (s *EnvelopeSink) Result(command string, runErr error) Envelope

type ErrorAction ¶ added in v0.2.0

type ErrorAction struct {
	Label string
	Value string
}

type ErrorCategory ¶ added in v0.17.0

type ErrorCategory string

ErrorCategory is a coarse, small-cardinality grouping of ErrorCode values, additive alongside Code (not a replacement for it — see design.md's naming decisions). A caller that only wants to distinguish broad kinds of failure (an environment problem vs. a usage problem vs. an auth problem) can switch on the ~8 Category values instead of the ~32 Code values; Code remains the primary, stable identifier for anything more specific.

const (
	// CategoryRuntime: something outside lstk's control (Docker, network, a
	// missing external binary) is the problem.
	CategoryRuntime ErrorCategory = "RUNTIME"
	// CategoryEmulator: the emulator isn't in the state this command needs.
	CategoryEmulator ErrorCategory = "EMULATOR"
	// CategoryAuth: identity, credentials, or license/entitlement.
	CategoryAuth ErrorCategory = "AUTH"
	// CategoryResource: a referenced thing (by name or ref) doesn't exist or
	// is invalid. Named generically, not e.g. "SNAPSHOT", so a future
	// non-snapshot resource error has somewhere to land without a new category.
	CategoryResource ErrorCategory = "RESOURCE"
	// CategoryConfig: lstk's own configuration is the problem.
	CategoryConfig ErrorCategory = "CONFIG"
	// CategoryUsage: the invocation itself needs to change (flags, args,
	// confirmation, capability).
	CategoryUsage ErrorCategory = "USAGE"
	// CategoryInternal: catch-all — unexpected failure or user-initiated
	// interruption.
	CategoryInternal ErrorCategory = "INTERNAL"
	// CategoryIAC: the workspace's infrastructure-as-code is the problem —
	// the domain `lstk deploy` operates in.
	CategoryIAC ErrorCategory = "IAC"
)

type ErrorCode ¶ added in v0.17.0

type ErrorCode string

ErrorCode is a stable, machine-readable identifier for a JSON envelope error. Values are documented in the error-codes OpenSpec capability; a call site with no applicable code SHALL use ErrInternal rather than inventing a new one.

const (
	ErrRuntimeUnavailable     ErrorCode = "RUNTIME_UNAVAILABLE"
	ErrImagePullFailed        ErrorCode = "IMAGE_PULL_FAILED"
	ErrEmulatorNotRunning     ErrorCode = "EMULATOR_NOT_RUNNING"
	ErrEmulatorAlreadyRunning ErrorCode = "EMULATOR_ALREADY_RUNNING"
	ErrEmulatorWrongType      ErrorCode = "EMULATOR_WRONG_TYPE"
	ErrEmulatorNotConfigured  ErrorCode = "EMULATOR_NOT_CONFIGURED"
	ErrEmulatorStartFailed    ErrorCode = "EMULATOR_START_FAILED"
	ErrAuthRequired           ErrorCode = "AUTH_REQUIRED"
	ErrAuthLoginFailed        ErrorCode = "AUTH_LOGIN_FAILED"
	ErrCredentialsMissing     ErrorCode = "CREDENTIALS_MISSING"
	ErrLicenseInvalid         ErrorCode = "LICENSE_INVALID"
	ErrLicenseUnsupportedTag  ErrorCode = "LICENSE_UNSUPPORTED_TAG"
	ErrLicenseNotCovered      ErrorCode = "LICENSE_NOT_COVERED"
	ErrSnapshotNotFound       ErrorCode = "SNAPSHOT_NOT_FOUND"
	ErrSnapshotInvalidRef     ErrorCode = "SNAPSHOT_INVALID_REF"
	ErrSnapshotRemoteError    ErrorCode = "SNAPSHOT_REMOTE_ERROR"
	ErrSnapshotBucketNotFound ErrorCode = "SNAPSHOT_BUCKET_NOT_FOUND"
	ErrConfigInvalid          ErrorCode = "CONFIG_INVALID"
	ErrConfigNotFound         ErrorCode = "CONFIG_NOT_FOUND"
	ErrIntegrationNotSetUp    ErrorCode = "INTEGRATION_NOT_SET_UP"
	ErrDependencyMissing      ErrorCode = "DEPENDENCY_MISSING"
	ErrDNSResolutionRequired  ErrorCode = "DNS_RESOLUTION_REQUIRED"
	ErrPortConflict           ErrorCode = "PORT_CONFLICT"
	ErrConfirmationRequired   ErrorCode = "CONFIRMATION_REQUIRED"
	ErrValidationError        ErrorCode = "VALIDATION_ERROR"
	ErrUsageError             ErrorCode = "USAGE_ERROR"
	ErrNotJSONCapable         ErrorCode = "NOT_JSON_CAPABLE"
	ErrNetworkError           ErrorCode = "NETWORK_ERROR"
	ErrCancelled              ErrorCode = "CANCELLED"
	ErrInternal               ErrorCode = "INTERNAL_ERROR"
	ErrIACFileNotFound        ErrorCode = "IAC_FILE_NOT_FOUND"
	ErrIACNoToolDetected      ErrorCode = "IAC_NO_TOOL_DETECTED"
	ErrIACToolAmbiguous       ErrorCode = "IAC_TOOL_AMBIGUOUS"
	ErrIACDeployFailed        ErrorCode = "IAC_DEPLOY_FAILED"
)

func (c ErrorCode) Category() ErrorCategory

func (c ErrorCode) Retryable() bool

type ErrorEvent ¶ added in v0.2.0

type ErrorEvent struct {
	Title   string
	Summary string
	Detail  string
	Actions []ErrorAction
	// Code classifies the error for JSON output. Empty means "not yet
	// classified" — EnvelopeSink falls back to ErrInternal. PlainSink and
	// TUISink ignore this field.
	Code ErrorCode
}

type Event ¶

type Event interface {
	// contains filtered or unexported methods
}

Event is a sealed marker — only event types in this package implement it, so Sink.Emit rejects unknown types at compile time.

type ExitCodeError ¶ added in v0.17.0

type ExitCodeError struct {
	Err  error
	Code int
}

ExitCodeError wraps an error with the explicit process exit code it should produce, mirroring how *exec.ExitError already carries a proxied command's exit code. Used for the JSON envelope's exit-code conventions (0/1/2/3/4) — main.go checks for this type the same way it already checks for *exec.ExitError.

func (e *ExitCodeError) Error() string

func (e *ExitCodeError) Unwrap() error

type Format ¶ added in v0.17.0

type Format string

Format identifies how an Envelope is serialized to bytes. FormatJSON is the only value implemented today; the type exists so a future serialization (e.g. YAML) is a new Format value and marshaler, not a rewrite of the EnvelopeSink accumulation logic below.

const FormatJSON Format = "json"

type InputOption ¶

type InputOption struct {
	Key   string
	Label string
}

type InputResponse ¶

type InputResponse struct {
	SelectedKey string
	Cancelled   bool
}

type InstanceInfoEvent ¶ added in v0.5.0

type InstanceInfoEvent struct {
	EmulatorName  string
	Version       string
	Host          string
	ContainerName string
	Uptime        time.Duration
	Persistence   bool
}

type JsonEmulatorEntry ¶ added in v0.17.0

type JsonEmulatorEntry interface {
	// contains filtered or unexported methods
}

JsonEmulatorEntry is a per-emulator entry in a command's data.emulators list. Sealed to this package so a new per-command shape (JsonStartedEmulator, ...) is added deliberately here, alongside the others, rather than accepted as a bare `any` at the call site.

type JsonEmulatorRef ¶ added in v0.17.0

type JsonEmulatorRef struct {
	Type string `json:"type"`
	Name string `json:"name"`
}

JsonEmulatorRef identifies an emulator.

type JsonResourceSummary ¶ added in v0.23.0

type JsonResourceSummary struct {
	Resources int `json:"resources"`
	Services  int `json:"services"`
}

JsonResourceSummary is the resource/service counts for `status --resources`.

type JsonStatusEmulator ¶ added in v0.23.0

type JsonStatusEmulator struct {
	Type            string               `json:"type"`
	Running         bool                 `json:"running"`
	Health          *string              `json:"health"`
	Name            string               `json:"name,omitempty"`
	Version         string               `json:"version,omitempty"`
	Host            string               `json:"host,omitempty"`
	UptimeSeconds   *int64               `json:"uptimeSeconds,omitempty"`
	Persistence     *bool                `json:"persistence,omitempty"`
	ResourceSummary *JsonResourceSummary `json:"resourceSummary,omitempty"`
	Resources       []JsonStatusResource `json:"resources,omitempty"`
}

JsonStatusEmulator is the per-emulator entry in `status`'s data.emulators. Detail fields are omitted for a non-running emulator, not nulled.

type JsonStatusResource ¶ added in v0.23.0

type JsonStatusResource struct {
	Service string `json:"service"`
	Name    string `json:"name"`
	Region  string `json:"region"`
	Account string `json:"account"`
}

JsonStatusResource is one deployed resource for `status --resources`.

type JsonStoppedEmulator ¶ added in v0.17.0

type JsonStoppedEmulator struct {
	JsonEmulatorRef
	WasRunning bool `json:"wasRunning"`
}

JsonStoppedEmulator is the per-emulator entry in `stop`'s data.emulators.

type LocalSnapshotSavedEvent ¶ added in v0.19.0

type LocalSnapshotSavedEvent struct {
	Path     string
	Services []string
	Size     int64
}

LocalSnapshotSavedEvent reports a snapshot saved to a local file. Services lists what was actually captured (all services when no --services filter was requested).

type LogLevel ¶ added in v0.5.2

type LogLevel int

const (
	LogLevelUnknown LogLevel = iota
	LogLevelDebug
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

type LogLineEvent ¶ added in v0.4.0

type LogLineEvent struct {
	Source string
	Line   string
	Level  LogLevel
}

type LogLinePrinter ¶ added in v0.20.0

type LogLinePrinter interface {
	PrintLogLine(event LogLineEvent)
}

LogLinePrinter abstracts Bubble Tea's Program.Println — permanent output that persists across renders, unlike a Sender's capped/repainted lines.

type MessageEvent ¶ added in v0.2.0

type MessageEvent struct {
	Severity MessageSeverity
	Text     string
}

type MessageSeverity ¶ added in v0.2.0

type MessageSeverity int

const (
	SeverityInfo      MessageSeverity = iota
	SeveritySuccess                   // positive outcome
	SeverityNote                      // informational
	SeverityWarning                   // cautionary
	SeveritySecondary                 // subdued/decorative text
)

type PlainSink ¶

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

func NewPlainSink(out io.Writer) *PlainSink

func (s *PlainSink) Emit(event Event)

func (s *PlainSink) Err() error

type PodSnapshotRemovedEvent ¶ added in v0.12.0

type PodSnapshotRemovedEvent struct {
	PodName string
}

type PodSnapshotSavedEvent ¶ added in v0.9.0

type PodSnapshotSavedEvent struct {
	PodName  string
	Version  int
	Services []string
	Size     int64
}

type ProgressEvent ¶

type ProgressEvent struct {
	Container string
	LayerID   string
	Status    string
	Current   int64
	Total     int64
}

type PullSkippableEvent ¶ added in v0.15.0

type PullSkippableEvent struct {
	Image  string
	SkipCh chan<- struct{}
}

PullSkippableEvent signals that an in-flight image pull can be abandoned in favor of an already-present local image. The domain emits it once real layer download begins (interactive mode, with a local copy present); the TUI binds ESC during the pull to send on SkipCh, which the domain selects on to cancel the pull and fall back to the local image. Never emitted in non-interactive mode, so PlainSink never needs to answer it.

type RemoteSnapshotSavedEvent ¶ added in v0.15.0

type RemoteSnapshotSavedEvent struct {
	PodName  string
	Location string
	Version  int
	Services []string
	Size     int64
}

RemoteSnapshotSavedEvent reports a snapshot saved to a remote storage backend (e.g. an S3 bucket). Location is the user-facing remote target (e.g. an s3:// URL) and PodName is the snapshot's identity within that remote.

type ResourceSummaryEvent ¶ added in v0.5.0

type ResourceSummaryEvent struct {
	Resources int
	Services  int
}

type Sender ¶

type Sender interface {
	Send(msg any)
}

Sender abstracts Bubble Tea's Program.Send to keep TUISink decoupled and testable.

type SilentError ¶ added in v0.2.0

type SilentError struct {
	Err error
}

SilentError wraps an error that has already been displayed to the user through the sink mechanism. Callers should check for this type and skip printing the error again.

func NewSilentError(err error) *SilentError

func (e *SilentError) Error() string

func (e *SilentError) Unwrap() error

type Sink ¶

type Sink interface {
	Emit(event Event)
}

type SinkFunc ¶

type SinkFunc func(event Event)

func (f SinkFunc) Emit(event Event)

type SnapshotDiffEvent ¶ added in v0.19.0

type SnapshotDiffEvent struct {
	PodName  string
	Version  int
	Strategy string
	Services map[string]SnapshotDiffServiceResult
}

SnapshotDiffEvent reports a dry-run diff between a cloud snapshot and the running state. Version is the pinned snapshot version, or 0 for the latest.

type SnapshotDiffServiceResult ¶ added in v0.19.0

type SnapshotDiffServiceResult struct {
	Additions     int
	Modifications int
}

type SnapshotLoadedEvent ¶ added in v0.10.0

type SnapshotLoadedEvent struct {
	Source   string   // display source shown to the user (e.g. "./snap.snapshot" or "pod:my-baseline")
	Services []string // services restored
}

type SnapshotResourceCount ¶ added in v0.13.0

type SnapshotResourceCount struct {
	Count int
	Noun  string
}

SnapshotResourceCount is a count of one resource kind, e.g. {Count: 3, Noun: "buckets"}.

type SnapshotResourceLine ¶ added in v0.13.0

type SnapshotResourceLine struct {
	Service string
	Counts  []SnapshotResourceCount
}

SnapshotResourceLine groups the resource counts of a single service.

type SnapshotShownEvent ¶ added in v0.13.0

type SnapshotShownEvent struct {
	Name              string
	Version           int
	Created           *time.Time
	Size              int64
	LocalStackVersion string
	Message           string
	Services          []string
	Resources         []SnapshotResourceLine
}

SnapshotShownEvent reports the metadata of a single cloud snapshot for the `snapshot show` command. Created is nil and Resources is empty when the platform has no value for them; the formatter omits those sections.

type SpinnerEvent ¶ added in v0.2.0

type SpinnerEvent struct {
	Active      bool
	Text        string
	MinDuration time.Duration // Minimum time spinner should display (0 = use default)
}

func SpinnerStart(text string) SpinnerEvent

func SpinnerStartWithDuration(text string, minDuration time.Duration) SpinnerEvent

func SpinnerStop() SpinnerEvent

type TUISink ¶

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

func NewStreamingLogSink(sender Sender, logPrinter LogLinePrinter) *TUISink

func NewTUISink(sender Sender) *TUISink

func (s *TUISink) Emit(event Event)

type TableEvent ¶ added in v0.5.0

type TableEvent struct {
	Headers []string
	Rows    [][]string
}

type UpdateAppliedEvent ¶ added in v0.17.0

type UpdateAppliedEvent struct {
	CurrentVersion string
	UpdatedVersion string
	Method         string
}

UpdateAppliedEvent reports that an update was downloaded and installed.

type UpdateCheckedEvent ¶ added in v0.17.0

type UpdateCheckedEvent struct {
	CurrentVersion string
	LatestVersion  string
	Available      bool
	DevBuild       bool
}

UpdateCheckedEvent reports the result of an update check. It always fires once per Check call — DevBuild, then Available, discriminate which of the three possible outcomes (dev build skipped the check / already up to date / an update is available) the formatter should render. LatestVersion is empty when DevBuild is true (the check never ran).

type UserInputDismissEvent ¶ added in v0.22.1

type UserInputDismissEvent struct {
	ResponseCh chan<- InputResponse
}

UserInputDismissEvent removes a pending prompt when the condition that required input resolves on its own. ResponseCh identifies the exact request so a late dismissal cannot hide a newer prompt.

type UserInputRequestEvent ¶

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

Base struct for all user input requests. Not to be instantiated directly. Build user input requests with typical constructors defined in prompt.go, e.g. Confirm, ActionChoice, or Acknowledge.

func Acknowledge(prompt, label string, responseCh chan<- InputResponse) UserInputRequestEvent

func ActionChoice(prompt string, options []InputOption, responseCh chan<- InputResponse) UserInputRequestEvent

? License validation failed: token expired.
● [ENTER] Log in again
○ [ESC] Exit

func Confirm(prompt string, def ConfirmDefault, responseCh chan<- InputResponse) UserInputRequestEvent

func (e UserInputRequestEvent) Options() []InputOption

func (e UserInputRequestEvent) Prompt() string

func (e UserInputRequestEvent) ResponseCh() chan<- InputResponse

func (e UserInputRequestEvent) Vertical() bool

type Warning ¶ added in v0.17.0

type Warning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

Warning is a non-fatal notice surfaced alongside a successful result.