Documentation
¶
Overview ¶
Package workflow is a standalone workflow runner for .asc/workflow.json files. It has zero imports from the rest of the codebase. Only depends on Go stdlib plus tidwall/jsonc for JSONC comment support in load.go.
Index ¶
Constants ¶
const DefaultPath = ".asc/workflow.json"
DefaultPath is the default location for the workflow definition file.
const MaxCallDepth = 16
MaxCallDepth is the maximum nesting depth for sub-workflow calls.
Variables ¶
var ( // ErrWorkflowRead indicates workflow file read failure. ErrWorkflowRead = errors.New("read workflow") // ErrWorkflowParseJSON indicates workflow JSON decode failure. ErrWorkflowParseJSON = errors.New("parse workflow JSON") )
Functions ¶
Types ¶
type Definition ¶
type Definition struct {
Env map[string]string `json:"env,omitempty"`
BeforeAll string `json:"before_all,omitempty"`
AfterAll string `json:"after_all,omitempty"`
Error string `json:"error,omitempty"`
Workflows map[string]Workflow `json:"workflows"`
}
Definition is the top-level .asc/workflow.json schema.
func Load ¶
func Load(path string) (*Definition, error)
Load reads and validates a workflow definition file.
func LoadUnvalidated ¶
func LoadUnvalidated(path string) (*Definition, error)
LoadUnvalidated reads and parses a workflow definition file without validation.
type HookResult ¶
type HookResult struct {
Command string `json:"command,omitempty"`
Status string `json:"status"`
DurationMS int64 `json:"duration_ms"`
Error string `json:"error,omitempty"`
}
HookResult records execution of a hook command (before_all/after_all/error).
type HooksResult ¶
type HooksResult struct {
BeforeAll *HookResult `json:"before_all,omitempty"`
AfterAll *HookResult `json:"after_all,omitempty"`
Error *HookResult `json:"error,omitempty"`
}
HooksResult records hook outcomes for a run.
type ResumeInfo ¶
type ResumeInfo struct {
Command string `json:"command,omitempty"`
}
ResumeInfo describes how to continue a partially completed workflow run.
type RunOptions ¶
type RunOptions struct {
WorkflowName string
Params map[string]string
DryRun bool
Stdout io.Writer
Stderr io.Writer
WorkflowFile string
StateDir string
ResumeRunID string
}
RunOptions configures a workflow execution.
type RunResult ¶
type RunResult struct {
Workflow string `json:"workflow"`
Status string `json:"status"`
Error string `json:"error,omitempty"`
FailedStep string `json:"failed_step,omitempty"`
Recoverable bool `json:"recoverable,omitempty"`
RunID string `json:"run_id,omitempty"`
RunFile string `json:"run_file,omitempty"`
Resumed bool `json:"resumed,omitempty"`
Resume *ResumeInfo `json:"resume,omitempty"`
Outputs map[string]map[string]string `json:"outputs,omitempty"`
Hooks *HooksResult `json:"hooks,omitempty"`
Steps []StepResult `json:"steps"`
DurationMS int64 `json:"duration_ms"`
}
RunResult is the structured output of a workflow execution.
func Run ¶
func Run(ctx context.Context, def *Definition, opts RunOptions) (*RunResult, error)
Run executes a named workflow from the Definition.
type Step ¶
type Step struct {
Run string `json:"run,omitempty"`
Workflow string `json:"workflow,omitempty"`
Name string `json:"name,omitempty"`
If string `json:"if,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: "..."} as shorthand.
func (*Step) UnmarshalJSON ¶
UnmarshalJSON handles the flexible step format:
- bare string → Step{Run: "..."}
- object → normal unmarshal
type StepResult ¶
type StepResult struct {
Index int `json:"index"`
Name string `json:"name,omitempty"`
Command string `json:"command,omitempty"`
Workflow string `json:"workflow,omitempty"`
ParentWorkflow string `json:"parent_workflow,omitempty"`
Status string `json:"status"`
DurationMS int64 `json:"duration_ms"`
Error string `json:"error,omitempty"`
Outputs map[string]string `json:"outputs,omitempty"`
}
StepResult records one executed step.
type ValidationCode ¶
type ValidationCode string
ValidationCode classifies validation failures.
const ( ErrNoWorkflows ValidationCode = "no_workflows" ErrInvalidWorkflowName ValidationCode = "invalid_workflow_name" ErrEmptySteps ValidationCode = "empty_steps" 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" )
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 a structured workflow validation failure.
func Validate ¶
func Validate(def *Definition) []*ValidationError
Validate checks a Definition for structural errors. Returns all validation errors found (not just the first).
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Source Files