workflow

Documentation

Overview

Package workflow provides a standalone workflow runner for .gplay/workflows/*.json files. It has zero imports from the rest of the codebase, depending only on Go stdlib.

Index

• func Interpolate(template string, vars map[string]string) (string, error)
• func SaveState(path string, result *ExecutionResult) error
• type Definition
  • func LoadDefinition(path string) (*Definition, error)
• type ExecuteOptions
• type ExecutionResult
  • func Execute(ctx context.Context, workflow *Workflow, params map[string]string, ...) (*ExecutionResult, error)
  • func ExecuteDefinition(ctx context.Context, def *Definition, workflowName string, ...) (*ExecutionResult, error)
  • func LoadState(path string) (*ExecutionResult, error)
• type Param
• type Step
  • func (s Step) Action() string
  • func (s Step) Predicate() string
  • func (s *Step) UnmarshalJSON(data []byte) error
• type StepResult
• type ValidationCode
• type ValidationError
  • func Validate(def *Definition) []*ValidationError
  • func (e *ValidationError) Error() string
• type Workflow
  • func Load(path string) (*Workflow, error)
  • func SelectWorkflow(def *Definition, implicitName, explicitName string) (string, Workflow, error)

Functions

func Interpolate

func Interpolate(template string, vars map[string]string) (string, error)

Interpolate performs variable substitution on a template string. It supports {{ .varname }} syntax and {{ .VAR | default "fallback" }} for defaults. Returns an error if a required variable (no default) is undefined.

func SaveState

func SaveState(path string, result *ExecutionResult) error

SaveState persists execution results to disk for resume support.

Types

type Definition

type Definition struct {
	Workflows map[string]Workflow `json:"workflows"`
}

Definition is the normalized workflow definition format. New files should use the `workflows` map. Legacy single-workflow files are still supported and are wrapped into a one-entry Definition at load time.

func LoadDefinition

func LoadDefinition(path string) (*Definition, error)

LoadDefinition reads and parses a workflow definition from a JSON file. It supports both the new `workflows` schema and the legacy single-workflow schema used by earlier gplay versions.

type ExecuteOptions

type ExecuteOptions struct {
	DryRun    bool
	Resume    bool
	Stdout    io.Writer
	Stderr    io.Writer
	StatePath string
}

ExecuteOptions configures workflow execution.

type ExecutionResult

type ExecutionResult struct {
	Workflow    string            `json:"workflow"`
	Steps       []StepResult      `json:"steps"`
	Success     bool              `json:"success"`
	ElapsedTime time.Duration     `json:"elapsed_time"`
	Outputs     map[string]string `json:"outputs,omitempty"`
}

ExecutionResult is the structured output of a workflow execution.

func Execute

func Execute(ctx context.Context, workflow *Workflow, params map[string]string, opts ExecuteOptions) (*ExecutionResult, error)

Execute runs a single workflow using the legacy API.

func ExecuteDefinition

func ExecuteDefinition(ctx context.Context, def *Definition, workflowName string, params map[string]string, opts ExecuteOptions) (*ExecutionResult, error)

ExecuteDefinition runs one named workflow from a definition, including any referenced child workflows.

func LoadState

func LoadState(path string) (*ExecutionResult, error)

LoadState reads a previously saved execution result from disk. Returns nil, nil if the file does not exist.

type Param

type Param struct {
	Name     string `json:"name"`
	Required bool   `json:"required"`
	Default  string `json:"default,omitempty"`
}

Param declares a workflow parameter.

type Step

type Step struct {
	Name       string            `json:"name,omitempty"`
	Run        string            `json:"run,omitempty"`
	Command    string            `json:"command,omitempty"`
	Workflow   string            `json:"workflow,omitempty"`
	ContinueOn string            `json:"continue_on,omitempty"` // "error" to continue on failure
	If         string            `json:"if,omitempty"`          // skip if evaluates to false
	Condition  string            `json:"condition,omitempty"`
	With       map[string]string `json:"with,omitempty"`
	Outputs    map[string]string `json:"outputs,omitempty"`
}

Step is one executable action in a workflow. Bare JSON strings unmarshal to Step{Run: "..."}.

`command` and `condition` remain supported as legacy aliases for `run` and `if`, so existing workflow files continue to work.

func (Step) Action

func (s Step) Action() string

Action returns the normalized shell action for a step.

func (Step) Predicate

func (s Step) Predicate() string

Predicate returns the normalized conditional variable for a step.

func (*Step) UnmarshalJSON

func (s *Step) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the flexible step format:

• bare string -> Step{Run: "..."}
• object -> normal unmarshal

type StepResult

type StepResult struct {
	Path     string            `json:"path,omitempty"`
	Workflow string            `json:"workflow,omitempty"`
	Name     string            `json:"name"`
	Command  string            `json:"command"`
	Stdout   string            `json:"stdout"`
	Stderr   string            `json:"stderr"`
	ExitCode int               `json:"exit_code"`
	Skipped  bool              `json:"skipped"`
	Outputs  map[string]string `json:"outputs,omitempty"`
}

StepResult records one executed step.

type ValidationCode

type ValidationCode string

ValidationCode classifies workflow definition errors.

const (
	ErrNoWorkflows                 ValidationCode = "no_workflows"
	ErrInvalidWorkflowName         ValidationCode = "invalid_workflow_name"
	ErrEmptySteps                  ValidationCode = "empty_steps"
	ErrDuplicateStepName           ValidationCode = "duplicate_step_name"
	ErrStepNoAction                ValidationCode = "step_no_action"
	ErrStepEmptyRun                ValidationCode = "step_empty_run"
	ErrStepConflict                ValidationCode = "step_run_and_workflow"
	ErrWorkflowNotFound            ValidationCode = "workflow_not_found"
	ErrCyclicReference             ValidationCode = "cyclic_reference"
	ErrStepWithOnRun               ValidationCode = "step_with_on_run"
	ErrStepOutputsOnWorkflow       ValidationCode = "step_outputs_on_workflow"
	ErrStepOutputsRequireName      ValidationCode = "step_outputs_require_name"
	ErrDuplicateOutputProducerName ValidationCode = "duplicate_output_producer_name"
	ErrInvalidOutputName           ValidationCode = "invalid_output_name"
	ErrInvalidOutputExpr           ValidationCode = "invalid_output_expr"
	ErrDuplicateParamName          ValidationCode = "duplicate_param_name"
	ErrEmptyParamName              ValidationCode = "empty_param_name"
)

type ValidationError

type ValidationError struct {
	Code     ValidationCode `json:"code"`
	Workflow string         `json:"workflow,omitempty"`
	Step     int            `json:"step,omitempty"`
	Message  string         `json:"message"`
}

ValidationError describes one structured workflow validation failure.

func Validate

func Validate(def *Definition) []*ValidationError

Validate checks a workflow definition for structural errors. It returns all detected errors for stable CLI reporting.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type Workflow

type Workflow struct {
	Name        string            `json:"name,omitempty"`
	Description string            `json:"description,omitempty"`
	Private     bool              `json:"private,omitempty"`
	Params      []Param           `json:"params,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	BeforeAll   []Step            `json:"before_all,omitempty"`
	Steps       []Step            `json:"steps"`
	AfterAll    []Step            `json:"after_all,omitempty"`
	OnError     []Step            `json:"on_error,omitempty"`
}

Workflow is one named automation sequence.

func Load

func Load(path string) (*Workflow, error)

Load reads a workflow file and returns a single workflow when the selection is unambiguous. It is kept for backward compatibility with the original single-workflow API.

func SelectWorkflow

func SelectWorkflow(def *Definition, implicitName, explicitName string) (string, Workflow, error)

SelectWorkflow chooses the workflow to run from a definition. If explicitName is set, it wins. Otherwise an implicitName match wins. If there is only one workflow, it is selected automatically.