step

package
v1.223.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: Apache-2.0 Imports: 53 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MetaStageIndex  = "_stage_index"
	MetaTotalStages = "_total_stages"
)

Stage tracking metadata keys.

Variables

View Source 
var (
	ErrCastStepRequiresSteps         = errUtils.ErrCastStepRequiresSteps
	ErrCastSessionRequiresActions    = errUtils.ErrCastSessionRequiresActions
	ErrInvalidCastMode               = errUtils.ErrInvalidCastMode
	ErrWriteActionRequiresText       = errUtils.ErrWriteActionRequiresText
	ErrKeyActionRequiresKey          = errUtils.ErrKeyActionRequiresKey
	ErrPauseActionRequiresDuration   = errUtils.ErrPauseActionRequiresDuration
	ErrWaitActionRequiresTextOrRegex = errUtils.ErrWaitActionRequiresTextOrRegex
	ErrUnsupportedSessionAction      = errUtils.ErrUnsupportedSessionAction
	ErrInvalidSimulateMode           = errUtils.ErrInvalidSimulateMode
	ErrSimulateTypedRequiresText     = errUtils.ErrSimulateTypedRequiresText
	ErrInvalidSimulateJitter         = errUtils.ErrInvalidSimulateJitter
	ErrUnsupportedPromptStyle        = errUtils.ErrUnsupportedPromptStyle
)
View Source 
var (
	ErrWorkdirPathRequired     = errUtils.ErrWorkdirPathRequired
	ErrWorkdirSourceRequired   = errUtils.ErrWorkdirSourceRequired
	ErrWorkdirSourceKeyInvalid = errUtils.ErrWorkdirSourceKeyInvalid
)

Functions

func BoolPtr 

func BoolPtr(b bool) *bool

BoolPtr is a helper to create a pointer to a bool value. Useful for setting ShowConfig fields in tests and configuration.

func Count 

func Count() int

Count returns the number of registered handlers.

func CountStages 

func CountStages(workflow *schema.WorkflowDefinition) int

CountStages counts the number of stage steps in a workflow.

func FormatStepLabel 

func FormatStepLabel(step *schema.WorkflowStep, workflow *schema.WorkflowDefinition, stepIndex, totalSteps int) string

FormatStepLabel formats the step label with optional count prefix. If show.count is enabled, returns "1/3 stepname" with stepname in muted style. Otherwise returns just "stepname" in muted style.

func GetShowConfig 

func GetShowConfig(step *schema.WorkflowStep, workflow *schema.WorkflowDefinition) *schema.ShowConfig

GetShowConfig returns the effective show config for a step. Performs deep merge: step-level values override workflow-level values. Unset values (nil) default to false.

func GetViewportConfig 

func GetViewportConfig(step *schema.WorkflowStep, workflow *schema.WorkflowDefinition) *schema.ViewportConfig

GetViewportConfig returns the effective viewport config for a step.

func IsExtendedStepType 

func IsExtendedStepType(stepType string) bool

IsExtendedStepType checks if a step type is an extended type (not atmos or shell).

func List 

func List() map[string]StepHandler

List returns all registered handlers.

func ListByCategory 

func ListByCategory() map[StepCategory][]StepHandler

ListByCategory returns handlers grouped by category.

func ListTypes 

func ListTypes() map[StepCategory][]string

ListTypes returns all available step type names grouped by category.

func Register 

func Register(handler StepHandler)

Register adds a step handler to the registry. Called from init() in each handler file. If a handler with the same name already exists, it is replaced.

func RegisterControlRunner added in v1.223.0 

func RegisterControlRunner(r ControlRunner)

RegisterControlRunner wires the control-step implementation. It is called from pkg/workflow's init so parallel/matrix steps work whenever that package is linked into the binary (always, for the CLI). The seam is what lets custom commands and lifecycle hooks run parallel/matrix steps through the registry — not just `atmos workflow`.

func RegisterEmulatorRunner added in v1.222.0 

func RegisterEmulatorRunner(r EmulatorRunner)

RegisterEmulatorRunner wires the emulator lifecycle implementation. It is called from pkg/component/emulator's init so the `emulator` step works whenever that package is linked into the binary (always, via cmd/emulator).

func RenderCommand 

func RenderCommand(step *schema.WorkflowStep, workflow *schema.WorkflowDefinition, command string)

RenderCommand renders the command before execution if show.command is enabled. Displays the command with a $ prefix for shell-like appearance.

func RunGrouped added in v1.223.0 

func RunGrouped(atmosConfig *schema.AtmosConfiguration, name, command string, fn func() error) error

RunGrouped runs a single step's execution (fn) wrapped in a collapsible CI log group when grouping is active for the current run (see ci.Group). The group label is the step `name` when set, falling back to the resolved `command`. Outside CI — or when grouping is disabled — fn runs unchanged.

This is the one place the step abstraction owns per-step CI log grouping, so both the workflow executor and the custom-command runner get identical behavior across every step type by routing their per-step dispatch through it.

func RunGroupedForType added in v1.223.0 

func RunGroupedForType(atmosConfig *schema.AtmosConfiguration, name, command, stepType string, fn func() error) error

RunGroupedForType is RunGrouped for ordinary step types, but deliberately skips grouping for exec steps. Exec steps may replace the Atmos process on Unix, so a deferred group close would never run after a successful handoff.

func ShowCommand 

func ShowCommand(cfg *schema.ShowConfig) bool

ShowCommand returns true if the command feature is enabled.

func ShowCount 

func ShowCount(cfg *schema.ShowConfig) bool

ShowCount returns true if the count feature is enabled.

func ShowFlags 

func ShowFlags(cfg *schema.ShowConfig) bool

ShowFlags returns true if the flags feature is enabled.

func ShowHeader 

func ShowHeader(cfg *schema.ShowConfig) bool

ShowHeader returns true if the header feature is enabled.

func ShowLabels added in v1.223.0 

func ShowLabels(cfg *schema.ShowConfig) bool

ShowLabels returns true unless labels are explicitly disabled.

func ShowProgress 

func ShowProgress(cfg *schema.ShowConfig) bool

ShowProgress returns true if the progress feature is enabled.

func ValidateStep 

func ValidateStep(step *schema.WorkflowStep) error

ValidateStep validates a step configuration.

func ValidateWorkflow 

func ValidateWorkflow(workflow *schema.WorkflowDefinition) []error

ValidateWorkflow validates all steps in a workflow definition.

Types

type AlertHandler 

type AlertHandler struct {
	BaseHandler
}

AlertHandler plays a terminal bell sound.

func (*AlertHandler) Execute 

func (h *AlertHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute plays the terminal bell and optionally displays a message.

func (*AlertHandler) Validate 

func (h *AlertHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type ArchiveHandler added in v1.223.0 

type ArchiveHandler struct {
	BaseHandler
}

ArchiveHandler packs (and, for zip/uncompressed tar, updates) zip/tar archives using pkg/archive — the Go standard library only, no external zip/tar binaries required. See docs/prd/archive-step.md. Available as a component lifecycle hook via the existing `kind: step` bridge (`kind: step` / `type: archive` / `with: {...}`); no dedicated hook kind is registered for it.

func (*ArchiveHandler) Execute added in v1.223.0 

func (h *ArchiveHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the configured archive action.

func (*ArchiveHandler) Validate added in v1.223.0 

func (h *ArchiveHandler) Validate(step *schema.WorkflowStep) error

Validate checks the archive step configuration before execution.

type AtmosHandler 

type AtmosHandler struct {
	BaseHandler
}

AtmosHandler executes atmos commands.

func (*AtmosHandler) Execute 

func (h *AtmosHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the atmos command.

func (*AtmosHandler) ExecuteWithWorkflow 

func (h *AtmosHandler) ExecuteWithWorkflow(ctx context.Context, step *schema.WorkflowStep, vars *Variables, workflow *schema.WorkflowDefinition) (*StepResult, error)

ExecuteWithWorkflow runs the atmos command with workflow context for output mode.

func (*AtmosHandler) Validate 

func (h *AtmosHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type BaseHandler 

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

BaseHandler provides common functionality for step handlers.

func NewBaseHandler 

func NewBaseHandler(name string, category StepCategory, requiresTTY bool, aliases ...string) BaseHandler

NewBaseHandler creates a new BaseHandler. Optional aliases are alternate type names that resolve to the same handler (e.g. "webhook" as an alias for "http").

func (BaseHandler) GetAliases added in v1.222.0 

func (h BaseHandler) GetAliases() []string

GetAliases returns the alternate type names that resolve to this handler.

func (BaseHandler) GetCategory 

func (h BaseHandler) GetCategory() StepCategory

GetCategory returns the step category.

func (BaseHandler) GetName 

func (h BaseHandler) GetName() string

GetName returns the step type name.

func (BaseHandler) RequiresTTY 

func (h BaseHandler) RequiresTTY() bool

RequiresTTY returns whether this handler requires an interactive terminal.

func (BaseHandler) ResolveCommand 

func (h BaseHandler) ResolveCommand(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (string, error)

ResolveCommand resolves Go templates in the command field.

func (BaseHandler) ResolveContent 

func (h BaseHandler) ResolveContent(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (string, error)

ResolveContent resolves Go templates in the content field.

func (BaseHandler) ResolveDefault added in v1.223.0 

func (h BaseHandler) ResolveDefault(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (string, error)

ResolveDefault resolves Go templates in the step's default value, returning an empty string when no default is configured. Shared by all interactive handlers so default resolution is defined in exactly one place.

func (BaseHandler) ResolvePrompt 

func (h BaseHandler) ResolvePrompt(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (string, error)

ResolvePrompt resolves Go templates in the prompt field.

func (BaseHandler) ValidateRequired 

func (h BaseHandler) ValidateRequired(step *schema.WorkflowStep, field, value string) error

ValidateRequired checks that a required field is not empty.

type CancelHandler added in v1.222.0 

type CancelHandler struct{ BaseHandler }

CancelHandler registers the `cancel` action step (tear down named background steps).

func (*CancelHandler) Execute added in v1.222.0 

func (h *CancelHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

func (*CancelHandler) Validate added in v1.222.0 

func (h *CancelHandler) Validate(step *schema.WorkflowStep) error

Validate requires `for:` to name at least one target.

type CastHandler added in v1.223.0 

type CastHandler struct {
	BaseHandler
}

func (*CastHandler) Execute added in v1.223.0 

func (h *CastHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

func (*CastHandler) ExecuteWithWorkflow added in v1.223.0 

func (h *CastHandler) ExecuteWithWorkflow(ctx context.Context, step *schema.WorkflowStep, vars *Variables, workflow *schema.WorkflowDefinition) (*StepResult, error)

func (*CastHandler) Validate added in v1.223.0 

func (h *CastHandler) Validate(step *schema.WorkflowStep) error

type ChooseHandler 

type ChooseHandler struct {
	BaseHandler
}

ChooseHandler prompts for single selection from a list.

func (*ChooseHandler) Execute 

func (h *ChooseHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for selection and returns the chosen value.

When there is no TTY (e.g. in CI) and a `default` is configured, the default is returned without prompting. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*ChooseHandler) Validate 

func (h *ChooseHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type ClearHandler 

type ClearHandler struct {
	BaseHandler
}

ClearHandler clears the current terminal line.

func (*ClearHandler) Execute 

func (h *ClearHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute clears the current terminal line.

func (*ClearHandler) Validate 

func (h *ClearHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type ConfirmHandler 

type ConfirmHandler struct {
	BaseHandler
}

ConfirmHandler prompts for yes/no confirmation.

func (*ConfirmHandler) Execute 

func (h *ConfirmHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for confirmation and returns "true" or "false".

When there is no TTY (e.g. in CI) and a `default` is configured, the default ("yes"/"true" => "true", otherwise "false") is returned without prompting. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*ConfirmHandler) Validate 

func (h *ConfirmHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type ContainerHandler added in v1.222.0 

type ContainerHandler struct {
	BaseHandler
}

ContainerHandler executes one-shot container steps.

func (*ContainerHandler) Execute added in v1.222.0 

func (h *ContainerHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the container step.

func (*ContainerHandler) ExecuteWithWorkflow added in v1.222.0 

func (h *ContainerHandler) ExecuteWithWorkflow(ctx context.Context, step *schema.WorkflowStep, vars *Variables, workflow *schema.WorkflowDefinition) (*StepResult, error)

ExecuteWithWorkflow runs the container step with workflow output inheritance.

func (*ContainerHandler) Validate added in v1.222.0 

func (h *ContainerHandler) Validate(step *schema.WorkflowStep) error

Validate checks container step configuration.

type ControlRunner added in v1.223.0 

type ControlRunner interface {
	// RunControl fans out a parallel/matrix step to its children and blocks
	// until they complete (honoring fail policy and output aggregation).
	RunControl(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)
}

ControlRunner executes control-flow steps (parallel/matrix). These step types fan out to child steps and need the scheduler/dependency graph plus, in a workflow, the run-scoped auth and output aggregation — machinery that lives in pkg/workflow, which pkg/runner/step cannot import without a cycle (the import direction is pkg/workflow -> pkg/runner/step). So the implementation is registered here at startup by pkg/workflow via RegisterControlRunner, the same reverse-dependency seam the emulator step uses (see emulator.go). When no runner is registered (e.g. a pure pkg/runner/step unit test that does not link pkg/workflow) the control handlers report that they require the workflow executor context.

type EmulatorHandler added in v1.222.0 

type EmulatorHandler struct {
	BaseHandler
}

EmulatorHandler manages an emulator component's lifecycle as a step, so component lifecycle hooks (`kind: step`, `type: emulator`) can bring a local cloud sandbox up before a terraform operation and tear it down after.

func (*EmulatorHandler) Execute added in v1.222.0 

func (h *EmulatorHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the emulator lifecycle action.

func (*EmulatorHandler) Validate added in v1.222.0 

func (h *EmulatorHandler) Validate(step *schema.WorkflowStep) error

Validate checks emulator step configuration.

type EmulatorRunner added in v1.222.0 

type EmulatorRunner interface {
	// Up starts (or reuses) the emulator component's container in the stack.
	// When ephemeral is true the instance runs without persistence.
	Up(ctx context.Context, component, stack string, ephemeral bool) error
	// Down stops and removes the emulator component's container.
	Down(ctx context.Context, component, stack string) error
	// Reset stops the container and wipes its persisted state.
	Reset(ctx context.Context, component, stack string) error
}

EmulatorRunner drives the lifecycle of an emulator component. It is the seam that lets the emulator step start/stop a sandbox without pkg/runner/step importing pkg/component/emulator directly (which would create an import cycle through internal/exec). The implementation is registered at startup via RegisterEmulatorRunner by pkg/component/emulator.

type EnvHandler 

type EnvHandler struct {
	BaseHandler
}

EnvHandler sets environment variables for subsequent steps.

func (*EnvHandler) Execute 

func (h *EnvHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute sets environment variables in the workflow context.

func (*EnvHandler) Validate 

func (h *EnvHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type ExecHandler added in v1.223.0 

type ExecHandler struct {
	BaseHandler
}

ExecHandler runs a command that replaces the Atmos process (exec semantics), so `type: exec` is a recognized, executable step type through the registry — previously it existed only in the legacy workflow executor.

func (*ExecHandler) Execute added in v1.223.0 

func (h *ExecHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute replaces the current process with the command (exec syscall on Unix). On success under Unix this call never returns; on Windows the command runs to completion and its error (if any) is returned. No retry wrapper is applied: a replaced process can never return to retry.

func (*ExecHandler) Validate added in v1.223.0 

func (h *ExecHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the exec step has a command. The "must be the final step" constraint is enforced at the workflow level (schema.ValidateWorkflowSteps); a standalone registry dispatch (hook, custom command) is inherently final.

type ExitHandler 

type ExitHandler struct {
	BaseHandler
}

ExitHandler exits the workflow with a specific exit code.

func (*ExitHandler) Execute 

func (h *ExitHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute exits the workflow with the specified exit code. It returns an error with the exit code attached that the workflow executor should handle to exit the program.

func (*ExitHandler) Validate 

func (h *ExitHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type FileHandler 

type FileHandler struct {
	BaseHandler
}

FileHandler prompts for file selection.

func (*FileHandler) Execute 

func (h *FileHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for file selection and returns the chosen path.

When there is no TTY (e.g. in CI) and a `default` is configured, the default path is returned without prompting. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*FileHandler) Validate 

func (h *FileHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type FilterHandler 

type FilterHandler struct {
	BaseHandler
}

FilterHandler prompts for fuzzy filter selection.

func (*FilterHandler) Execute 

func (h *FilterHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for filtered selection and returns the chosen value(s).

When there is no TTY (e.g. in CI) and a `default` is configured, the default is returned without prompting. For multi-select (`multiple: true` or `limit > 1`) the default is treated as a comma-separated list. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*FilterHandler) Validate 

func (h *FilterHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type FormatHandler 

type FormatHandler struct {
	BaseHandler
}

FormatHandler formats and displays text using Go templates.

func (*FormatHandler) Execute 

func (h *FormatHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute formats and displays the content.

func (*FormatHandler) Validate 

func (h *FormatHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type HTTPHandler added in v1.222.0 

type HTTPHandler struct {
	BaseHandler
}

HTTPHandler executes an HTTP request (GET, POST, and other verbs) with query, body, headers, timeouts, and retries. It composes with the step's `retry:` configuration.

func (*HTTPHandler) Execute added in v1.222.0 

func (h *HTTPHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute performs the HTTP request, applying per-attempt timeouts and retry.

func (*HTTPHandler) Validate added in v1.222.0 

func (h *HTTPHandler) Validate(step *schema.WorkflowStep) error

Validate checks the http step configuration before execution.

type HintHandler added in v1.223.0 

type HintHandler struct {
	BaseHandler
}

HintHandler displays a muted hint message with the Atmos hint UI style.

func (*HintHandler) Execute added in v1.223.0 

func (h *HintHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute displays the hint message.

func (*HintHandler) Validate added in v1.223.0 

func (h *HintHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type InputHandler 

type InputHandler struct {
	BaseHandler
}

InputHandler prompts for single-line text input.

func (*InputHandler) Execute 

func (h *InputHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for user input and returns the result.

When there is no TTY (e.g. in CI) and a `default` is configured, the default is returned without prompting. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*InputHandler) Validate 

func (h *InputHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type JUnitHandler added in v1.222.0 

type JUnitHandler struct {
	BaseHandler
}

JUnitHandler ingests JUnit XML files and surfaces them in CI: it renders a markdown step summary and emits inline annotations for failing/errored tests. It works with any test runner that produces JUnit (terraform/opentofu test, pytest, go-test→junit, …), usable from a workflow, custom command, or `kind: step` lifecycle hook.

func (*JUnitHandler) Execute added in v1.222.0 

func (h *JUnitHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute parses the JUnit files, writes a CI step summary, and emits annotations for failures.

func (*JUnitHandler) Validate added in v1.222.0 

func (h *JUnitHandler) Validate(step *schema.WorkflowStep) error

Validate checks junit step configuration.

type JoinHandler 

type JoinHandler struct {
	BaseHandler
}

JoinHandler joins multiple strings together.

func (*JoinHandler) Execute 

func (h *JoinHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute joins strings and returns the result.

func (*JoinHandler) Validate 

func (h *JoinHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type LinebreakHandler 

type LinebreakHandler struct {
	BaseHandler
}

LinebreakHandler outputs one or more blank lines.

func (*LinebreakHandler) Execute 

func (h *LinebreakHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute outputs the specified number of blank lines.

func (*LinebreakHandler) Validate 

func (h *LinebreakHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type LogHandler 

type LogHandler struct {
	BaseHandler
}

LogHandler logs a message using the atmos logger.

func (*LogHandler) Execute 

func (h *LogHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute logs the message at the specified level.

func (*LogHandler) Validate 

func (h *LogHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type MarkdownHandler 

type MarkdownHandler struct {
	BaseHandler
}

MarkdownHandler renders and displays markdown content.

func (*MarkdownHandler) Execute 

func (h *MarkdownHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute renders and displays the markdown content.

func (*MarkdownHandler) Validate 

func (h *MarkdownHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type MatrixHandler added in v1.222.0 

type MatrixHandler struct {
	BaseHandler
}

MatrixHandler registers the matrix workflow control step type.

func (*MatrixHandler) Execute added in v1.222.0 

func (h *MatrixHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute expands the matrix and fans its children out via the registered ControlRunner (see control_seam.go), so matrix steps work through the registry from custom commands and lifecycle hooks, not just `atmos workflow`.

func (*MatrixHandler) Validate added in v1.222.0 

func (h *MatrixHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the matrix control step is structurally valid and that no child step is interactive (interactive steps cannot run concurrently).

type OutputMode 

type OutputMode string

OutputMode controls how command output is displayed. 

const (
	// OutputModeViewport displays output in an interactive TUI pager.
	OutputModeViewport OutputMode = "viewport"
	// OutputModeRaw passes output directly to stdout/stderr.
	OutputModeRaw OutputMode = "raw"
	// OutputModeLog groups output with step boundaries.
	OutputModeLog OutputMode = "log"
	// OutputModeNone suppresses all output.
	OutputModeNone OutputMode = "none"
)

func GetOutputMode 

func GetOutputMode(step *schema.WorkflowStep, workflow *schema.WorkflowDefinition) OutputMode

GetOutputMode returns the effective output mode for a step. Checks step-level, workflow-level, and defaults.

type OutputModeWriter 

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

OutputModeWriter wraps command execution with the specified output mode.

func NewOutputModeWriter 

func NewOutputModeWriter(mode OutputMode, stepName string, viewport *schema.ViewportConfig, show ...*schema.ShowConfig) *OutputModeWriter

NewOutputModeWriter creates a new OutputModeWriter.

func (*OutputModeWriter) Execute 

func (w *OutputModeWriter) Execute(cmd *exec.Cmd) (string, string, error)

Execute runs the command with the configured output mode.

func (*OutputModeWriter) ExecuteWithIO added in v1.222.0 

func (w *OutputModeWriter) ExecuteWithIO(runner func(stdout, stderr io.Writer) error) (string, string, error)

ExecuteWithIO runs a command-like operation with the configured output mode. The runner receives stdout and stderr writers to attach to the operation.

type PagerHandler 

type PagerHandler struct {
	BaseHandler
}

PagerHandler displays content in a scrollable pager.

func (*PagerHandler) Execute 

func (h *PagerHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute displays content in a pager.

func (*PagerHandler) Validate 

func (h *PagerHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields. Either content or path must be provided.

type ParallelHandler added in v1.222.0 

type ParallelHandler struct {
	BaseHandler
}

ParallelHandler registers the parallel workflow control step type.

func (*ParallelHandler) Execute added in v1.222.0 

func (h *ParallelHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute fans the parallel step out to its children via the registered ControlRunner (see control_seam.go). The heavy scheduler/graph and (for `atmos workflow`) auth/output machinery lives in pkg/workflow and is reached through the seam, so parallel steps work through the registry — from custom commands and lifecycle hooks, not just `atmos workflow`.

func (*ParallelHandler) Validate added in v1.222.0 

func (h *ParallelHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the parallel control step is structurally valid and that no child step is interactive (interactive steps cannot run concurrently).

type Registry 

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

Registry manages step type handlers.

type RequireHandler added in v1.222.0 

type RequireHandler struct {
	BaseHandler
	// contains filtered or unexported fields
}

RequireHandler asserts that required CLI tools are on PATH and that required files and directories exist. It is a read-only preconditions gate: it never mutates PATH or the environment, which keeps it safe to run alongside other steps that may write to the shared step environment.

func (*RequireHandler) Execute added in v1.222.0 

func (h *RequireHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute verifies every declared requirement and fails with an aggregated, hinted error listing everything that is missing.

func (*RequireHandler) Validate added in v1.222.0 

func (h *RequireHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step declares at least one requirement.

type SayHandler added in v1.222.0 

type SayHandler struct {
	BaseHandler
}

SayHandler speaks the step content using text-to-speech, degrading to a formatted info message when audio is unavailable.

func (*SayHandler) Execute added in v1.222.0 

func (h *SayHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute speaks the content. The `print` field selects how the message is shown when (or whether) it is also printed.

func (*SayHandler) Validate added in v1.222.0 

func (h *SayHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type ScriptHandler added in v1.223.0 

type ScriptHandler struct {
	BaseHandler
}

ScriptHandler executes inline scripts with an explicit interpreter.

func (*ScriptHandler) Execute added in v1.223.0 

func (h *ScriptHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the script.

func (*ScriptHandler) ExecuteWithWorkflow added in v1.223.0 

func (h *ScriptHandler) ExecuteWithWorkflow(ctx context.Context, step *schema.WorkflowStep, vars *Variables, workflow *schema.WorkflowDefinition) (*StepResult, error)

ExecuteWithWorkflow runs the script with workflow-level output defaults.

func (*ScriptHandler) Validate added in v1.223.0 

func (h *ScriptHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the script step has required fields and does not use command.

type ShellHandler 

type ShellHandler struct {
	BaseHandler
}

ShellHandler executes shell commands.

func (*ShellHandler) Execute 

func (h *ShellHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the shell command.

func (*ShellHandler) ExecuteWithWorkflow 

func (h *ShellHandler) ExecuteWithWorkflow(ctx context.Context, step *schema.WorkflowStep, vars *Variables, workflow *schema.WorkflowDefinition) (*StepResult, error)

ExecuteWithWorkflow runs the shell command with workflow context for output mode.

func (*ShellHandler) Validate 

func (h *ShellHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type SleepHandler 

type SleepHandler struct {
	BaseHandler
}

SleepHandler pauses execution for a specified duration.

func (*SleepHandler) Execute 

func (h *SleepHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute pauses execution for the specified duration.

func (*SleepHandler) Validate 

func (h *SleepHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type Spacing 

type Spacing struct {
	Top    int
	Right  int
	Bottom int
	Left   int
}

Spacing represents padding or margin values for top, right, bottom, left.

type SpinHandler 

type SpinHandler struct {
	BaseHandler
}

SpinHandler displays a spinner while executing a command.

func (*SpinHandler) Execute 

func (h *SpinHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute runs the command with a spinner.

func (*SpinHandler) Validate 

func (h *SpinHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type StageHandler 

type StageHandler struct {
	BaseHandler
}

StageHandler displays workflow stage position among stage steps. Unlike the step count which shows position among all steps, stage shows position only among steps of type "stage".

func (*StageHandler) Execute 

func (h *StageHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute renders the stage indicator. Format: [Stage 1/3] Setup.

func (*StageHandler) Validate 

func (h *StageHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type StepCategory 

type StepCategory string

StepCategory groups step types for documentation and validation. 

const (
	// CategoryInteractive requires user input (TTY required).
	CategoryInteractive StepCategory = "interactive"
	// CategoryOutput displays formatted output.
	CategoryOutput StepCategory = "output"
	// CategoryUI displays status messages.
	CategoryUI StepCategory = "ui"
	// CategoryCommand executes commands.
	CategoryCommand StepCategory = "command"
)

type StepExecutor 

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

StepExecutor runs workflow steps using the step registry. This provides a simplified interface for executing steps with variable passing.

func NewStepExecutor 

func NewStepExecutor() *StepExecutor

NewStepExecutor creates a new step executor.

func NewStepExecutorWithVars 

func NewStepExecutorWithVars(vars *Variables) *StepExecutor

NewStepExecutorWithVars creates a new executor with pre-populated variables.

func (*StepExecutor) Execute 

func (e *StepExecutor) Execute(ctx context.Context, step *schema.WorkflowStep) (*StepResult, error)

Execute runs a single step and stores the result.

func (*StepExecutor) GetResult 

func (e *StepExecutor) GetResult(name string) (*StepResult, bool)

GetResult returns the result of a previously executed step.

func (*StepExecutor) RunAll 

func (e *StepExecutor) RunAll(ctx context.Context, workflow *schema.WorkflowDefinition) error

RunAll executes all steps in order.

func (*StepExecutor) SetAtmosConfig added in v1.223.0 

func (e *StepExecutor) SetAtmosConfig(config *schema.AtmosConfiguration)

SetAtmosConfig sets the active Atmos configuration for handlers that need process-level settings.

func (*StepExecutor) SetEnv 

func (e *StepExecutor) SetEnv(key, value string)

SetEnv sets an environment variable for use in templates.

func (*StepExecutor) SetFlag added in v1.222.0 

func (e *StepExecutor) SetFlag(key, value string)

SetFlag sets a workflow flag for use in templates.

func (*StepExecutor) SetWorkflow 

func (e *StepExecutor) SetWorkflow(workflow *schema.WorkflowDefinition)

SetWorkflow sets the workflow context for output mode inheritance.

func (*StepExecutor) Variables 

func (e *StepExecutor) Variables() *Variables

Variables returns the executor's variable store.

type StepHandler 

type StepHandler interface {
	// GetName returns the step type name (e.g., "input", "choose", "success").
	GetName() string

	// GetCategory returns the step category for grouping.
	GetCategory() StepCategory

	// Execute runs the step and returns the result.
	Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

	// Validate checks step configuration before execution.
	Validate(step *schema.WorkflowStep) error

	// RequiresTTY returns true if the step requires an interactive terminal.
	RequiresTTY() bool
}

StepHandler defines the interface for workflow step type handlers.

func Get 

func Get(typeName string) (StepHandler, bool)

Get returns a handler by type name, falling back to registered aliases.

type StepResult 

type StepResult struct {
	// Value is the primary output value (for variable capture).
	Value string
	// Values holds multiple values for multiselect operations.
	Values []string
	// Metadata contains additional data from the step execution.
	Metadata map[string]any
	// Outputs contains named outputs declared by the step.
	Outputs map[string]string
	// Skipped indicates if the step was skipped.
	Skipped bool
	// Error captures any error message from the step.
	Error string
}

StepResult captures the output of a step execution.

func NewStepResult 

func NewStepResult(value string) *StepResult

NewStepResult creates a new StepResult with the given value.

func (*StepResult) WithError 

func (r *StepResult) WithError(err string) *StepResult

WithError adds an error message to the result.

func (*StepResult) WithMetadata 

func (r *StepResult) WithMetadata(key string, value any) *StepResult

WithMetadata adds metadata to the result.

func (*StepResult) WithOutput added in v1.222.0 

func (r *StepResult) WithOutput(key, value string) *StepResult

WithOutput adds a declared output to the result.

func (*StepResult) WithSkipped 

func (r *StepResult) WithSkipped() *StepResult

WithSkipped marks the result as skipped.

func (*StepResult) WithValues 

func (r *StepResult) WithValues(values []string) *StepResult

WithValues adds multiple values to the result.

type StreamingOutputWriter 

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

StreamingOutputWriter handles real-time output streaming with prefix per line.

func NewStreamingOutputWriter 

func NewStreamingOutputWriter(prefix string, target io.Writer) *StreamingOutputWriter

NewStreamingOutputWriter creates a writer that prefixes each line.

func (*StreamingOutputWriter) Flush 

func (w *StreamingOutputWriter) Flush()

Flush writes any buffered content to the target.

func (*StreamingOutputWriter) String 

func (w *StreamingOutputWriter) String() string

String returns the captured output, flushing any buffered content first.

func (*StreamingOutputWriter) Write 

func (w *StreamingOutputWriter) Write(p []byte) (n int, err error)

Write implements io.Writer with line-buffering so prefix is applied per line.

type StyleHandler 

type StyleHandler struct {
	BaseHandler
}

StyleHandler applies terminal styling to text (like gum style).

func (*StyleHandler) Execute 

func (h *StyleHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute applies styling and displays the content.

func (*StyleHandler) Validate 

func (h *StyleHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type TableHandler 

type TableHandler struct {
	BaseHandler
}

TableHandler renders data as a formatted table.

func (*TableHandler) Execute 

func (h *TableHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute renders the table.

func (*TableHandler) Validate 

func (h *TableHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type TemplateRenderer added in v1.222.0 

type TemplateRenderer func(name, input string, data any) (string, error)

TemplateRenderer renders one template pass with the provided data.

type TitleHandler 

type TitleHandler struct {
	BaseHandler
}

TitleHandler sets the terminal window title.

func (*TitleHandler) Execute 

func (h *TitleHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute sets or restores the terminal window title.

func (*TitleHandler) Validate 

func (h *TitleHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has valid fields.

type ToastHandler 

type ToastHandler struct {
	BaseHandler
}

ToastHandler displays a styled message with icon (success, info, warning, error).

func (*ToastHandler) Execute 

func (h *ToastHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute displays the message with the appropriate style based on level.

func (*ToastHandler) Validate 

func (h *ToastHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type Variables 

type Variables struct {
	// Steps maps step names to their results.
	Steps map[string]*StepResult
	// Env contains environment variables.
	Env map[string]string
	// Flags contains workflow command-line flags exposed to step templates.
	Flags       map[string]string
	AtmosConfig *schema.AtmosConfiguration
	// contains filtered or unexported fields
}

Variables holds step outputs accessible via Go templates.

func NewVariables 

func NewVariables() *Variables

NewVariables creates a new Variables instance with OS environment pre-populated.

func (*Variables) EnsureBinaryInPath added in v1.223.0 

func (v *Variables) EnsureBinaryInPath(binaryPath string)

EnsureBinaryInPath prepends the directory of binaryPath to the PATH variable unless it is already present, matching the existing key's casing (Windows uses "Path"). Command- or step-level env can override PATH entirely; calling this afterwards preserves the guarantee that a bare `atmos` in steps resolves to the running binary.

func (*Variables) EnvSlice added in v1.222.0 

func (v *Variables) EnvSlice() []string

EnvSlice returns the variable environment as a sorted slice of "KEY=VALUE" entries, suitable for use as a subprocess environment. The slice is the complete environment (it includes the inherited OS environment loaded by NewVariables plus any workflow/step/identity-resolved entries), so callers can hand it to a container runtime via container.EnvSetter to carry credentials materialized by auth integrations (e.g. DOCKER_CONFIG for ECR login).

func (*Variables) GetStageIndex 

func (v *Variables) GetStageIndex() int

GetStageIndex returns the current stage index.

func (*Variables) GetTotalStages 

func (v *Variables) GetTotalStages() int

GetTotalStages returns the total number of stage steps.

func (*Variables) GetValue 

func (v *Variables) GetValue(stepName string) (string, bool)

GetValue returns a step's primary value.

func (*Variables) GetValues 

func (v *Variables) GetValues(stepName string) ([]string, bool)

GetValues returns a step's multiple values.

func (*Variables) IncrementStageIndex 

func (v *Variables) IncrementStageIndex() int

IncrementStageIndex increments and returns the current stage index.

func (*Variables) LoadOSEnv 

func (v *Variables) LoadOSEnv()

LoadOSEnv populates the Env map with all OS environment variables.

func (*Variables) ProtectTemplateRoots added in v1.222.0 

func (v *Variables) ProtectTemplateRoots(roots ...string)

ProtectTemplateRoots prevents template markers in selected roots from being re-evaluated during later render passes.

func (*Variables) Resolve 

func (v *Variables) Resolve(input string) (string, error)

Resolve resolves Go templates in the given string using variable data.

func (*Variables) ResolveEnvMap 

func (v *Variables) ResolveEnvMap(envMap map[string]string) (map[string]string, error)

ResolveEnvMap resolves Go templates in a map of environment variables.

func (*Variables) ResolveOutputs added in v1.222.0 

func (v *Variables) ResolveOutputs(outputs map[string]string, result *StepResult) (map[string]string, error)

ResolveOutputs resolves a step's declared outputs against the current result and all previously stored step results.

func (*Variables) ResolveWith added in v1.223.0 

func (v *Variables) ResolveWith(input string, envOverlay map[string]string) (string, error)

ResolveWith resolves Go templates in input using the current variable data with envOverlay merged on top of the persisted env for this call only. The overlay does not mutate the Variables' env, so a per-step environment does not leak into later steps' template context.

func (*Variables) Set 

func (v *Variables) Set(name string, result *StepResult)

Set stores a step result by name.

func (*Variables) SetAtmosConfig added in v1.223.0 

func (v *Variables) SetAtmosConfig(config *schema.AtmosConfiguration)

SetAtmosConfig stores the active Atmos configuration for step handlers that need to respect process-level settings such as native CI summary controls.

func (*Variables) SetEnv 

func (v *Variables) SetEnv(key, value string)

SetEnv sets an environment variable.

func (*Variables) SetFlag added in v1.222.0 

func (v *Variables) SetFlag(key, value string)

SetFlag sets a workflow flag variable.

func (*Variables) SetTemplateData added in v1.222.0 

func (v *Variables) SetTemplateData(data map[string]any)

SetTemplateData sets extra root values exposed during template resolution.

func (*Variables) SetTemplatePasses added in v1.222.0 

func (v *Variables) SetTemplatePasses(passes int)

SetTemplatePasses sets the maximum number of render passes used by Resolve.

func (*Variables) SetTemplateRenderer added in v1.222.0 

func (v *Variables) SetTemplateRenderer(renderer TemplateRenderer)

SetTemplateRenderer sets the one-pass renderer used by Resolve.

func (*Variables) SetTotalStages 

func (v *Variables) SetTotalStages(total int)

SetTotalStages sets the total number of stage steps in the workflow.

func (*Variables) SetWithOutputs added in v1.222.0 

func (v *Variables) SetWithOutputs(name string, result *StepResult, outputs map[string]string) error

SetWithOutputs evaluates declared outputs and stores a step result by name.

func (*Variables) TemplateData added in v1.222.0 

func (v *Variables) TemplateData() map[string]any

TemplateData returns the data structure used for Go template execution.

type WaitAllHandler added in v1.222.0 

type WaitAllHandler struct{ BaseHandler }

WaitAllHandler registers the `wait-all` action step (block until all background steps ready).

func (*WaitAllHandler) Execute added in v1.222.0 

func (h *WaitAllHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

func (*WaitAllHandler) Validate added in v1.222.0 

func (h *WaitAllHandler) Validate(step *schema.WorkflowStep) error

Validate is a no-op: wait-all takes no targets.

type WaitHandler added in v1.222.0 

type WaitHandler struct{ BaseHandler }

WaitHandler registers the `wait` action step (block until named background steps ready).

func (*WaitHandler) Execute added in v1.222.0 

func (h *WaitHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

func (*WaitHandler) Validate added in v1.222.0 

func (h *WaitHandler) Validate(step *schema.WorkflowStep) error

Validate requires `for:` to name at least one target.

type WorkdirHandler added in v1.223.0 

type WorkdirHandler struct {
	BaseHandler
}

WorkdirHandler provisions a mutable working directory from a source.

func (*WorkdirHandler) Execute added in v1.223.0 

func (h *WorkdirHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute provisions the configured source into the target path.

func (*WorkdirHandler) Validate added in v1.223.0 

func (h *WorkdirHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

type WriteHandler 

type WriteHandler struct {
	BaseHandler
}

WriteHandler prompts for multi-line text input.

func (*WriteHandler) Execute 

func (h *WriteHandler) Execute(ctx context.Context, step *schema.WorkflowStep, vars *Variables) (*StepResult, error)

Execute prompts for multi-line input and returns the result.

When there is no TTY (e.g. in CI) and a `default` is configured, the default text is returned without prompting. When there is no TTY and no `default` is set, resolveInteractive returns ErrStepTTYRequired.

func (*WriteHandler) Validate 

func (h *WriteHandler) Validate(step *schema.WorkflowStep) error

Validate checks that the step has required fields.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.