package workflow import ( "bytes" "crypto/sha256" "embed" "encoding/hex" "encoding/json" "fmt" "io/fs" "path" "slices" "strings" "gopkg.in/yaml.v3" "github.com/samcharles93/archie-core/internal/domain/workflow/task" ) // YAMLDefinition is the portable, versioned workflow representation. type YAMLDefinition struct { ID string `yaml:"id" json:"id"` // Package names the installed package that contributed this workflow. The // package projector sets it; a run of the workflow is bounded by the // authority accepted for that package. Package string `yaml:"package,omitempty" json:"package,omitempty"` Steps []StepRecord `yaml:"steps" json:"steps"` // WorkflowInterface declares the workflow's inputs, repository mode and // agent profile. task.WorkflowInterface `yaml:",inline" json:",inline"` } // repoFreeStepTypes are the step types that run without a repository. A // workflow whose repository is not required may use only these, since it may // run with no worktree at all. workflow.call needs none of the caller's own: // the callee's own repository mode decides whether its run clones. var repoFreeStepTypes = map[string]bool{ AgentRunStepName: true, WorkflowCallStepName: true, FinishStepName: true, HandoffStepName: true, ApproveStepName: true, CloseIssueStepName: true, CommentStepName: true, } // NeedsRepository reports whether a step type can run only with a worktree. func NeedsRepository(stepType string) bool { return !repoFreeStepTypes[stepType] } // StepRecord selects one registered step type and supplies its typed settings. type StepRecord struct { // ID names the step so later steps can reference its result. ID string `yaml:"id,omitempty" json:"id,omitempty"` Type string `yaml:"type,omitempty" json:"type,omitempty"` Settings yaml.Node `yaml:"settings,omitempty" json:"-"` // When skips the step unless the condition holds: a reference that must // be truthy, negated with !, or compared with == or != to a literal. When string `yaml:"when,omitempty" json:"when,omitempty"` // OnFailure is "park" (the default) or "continue". OnFailure string `yaml:"on_failure,omitempty" json:"on_failure,omitempty"` // Retry runs a failed step again before on_failure applies. Retry *RetryPolicy `yaml:"retry,omitempty" json:"retry,omitempty"` // Parallel makes this step a set of named branches that run at the same // time instead of a typed step. Each branch is a list of steps. Parallel map[string][]StepRecord `yaml:"parallel,omitempty" json:"parallel,omitempty"` // Switch makes this step a choice: the case named by a reference's value // runs, else the default, else nothing. Switch *SwitchStep `yaml:"switch,omitempty" json:"switch,omitempty"` } // SwitchStep runs the steps of the case whose key equals the value On // references, else the case named default, else nothing. type SwitchStep struct { On string `yaml:"on" json:"on"` Cases map[string][]StepRecord `yaml:"cases" json:"cases"` } const switchDefault = "default" // RetryPolicy is how often a failed step runs again, and how long it waits // between attempts. type RetryPolicy struct { Attempts int `yaml:"attempts" json:"attempts"` Backoff string `yaml:"backoff,omitempty" json:"backoff,omitempty"` } const onFailureContinue = "continue" type StepFactory func(yaml.Node) (Stage, error) // StepRegistry is the closed set of safe workflow operations available to YAML. type StepRegistry map[string]StepFactory // ParseDefinition strictly parses and validates one YAML workflow. func ParseDefinition(src string, registry StepRegistry) (YAMLDefinition, error) { var definition YAMLDefinition decoder := yaml.NewDecoder(strings.NewReader(src)) decoder.KnownFields(true) if err := decoder.Decode(&definition); err != nil { return YAMLDefinition{}, fmt.Errorf("parse workflow YAML: %w", err) } if strings.TrimSpace(definition.ID) == "" { return YAMLDefinition{}, fmt.Errorf("workflow id is required") } if len(definition.Steps) == 0 { return YAMLDefinition{}, fmt.Errorf("workflow %q has no steps", definition.ID) } if err := definition.Validate(); err != nil { return YAMLDefinition{}, fmt.Errorf("workflow %q: %w", definition.ID, err) } mode := definition.RepositoryMode() earlier := newRefScope(definition.Inputs) for i, step := range definition.Steps { if err := checkStep(step, mode, earlier, registry, false); err != nil { return YAMLDefinition{}, fmt.Errorf("workflow %q step %d: %w", definition.ID, i+1, err) } } return definition, nil } // PackageOf returns the package a pinned definition was projected from, or // empty for a workflow the operator wrote. func PackageOf(src string) string { var declared struct { Package string `yaml:"package"` } if err := yaml.Unmarshal([]byte(src), &declared); err != nil { return "" } return declared.Package } // StageNames returns the names a definition's steps run under, in order. It // reads a definition already pinned, so it decodes without validating. func StageNames(src string) ([]string, error) { var definition YAMLDefinition if err := yaml.Unmarshal([]byte(src), &definition); err != nil { return nil, fmt.Errorf("parse workflow YAML: %w", err) } names := make([]string, len(definition.Steps)) for i, step := range definition.Steps { names[i] = step.StageName() } return names, nil } // ParseAndCompile validates and compiles one definition in a single operation. func ParseAndCompile(src string, registry StepRegistry) (Workflow, error) { definition, err := ParseDefinition(src, registry) if err != nil { return Workflow{}, err } return Compile(definition, registry) } // DigestDefinition returns the immutable content identity stored with a run. func DigestDefinition(src string) string { sum := sha256.Sum256([]byte(src)) return hex.EncodeToString(sum[:]) } // DefinitionID returns the workflow id a definition declares without // compiling or validating it. func DefinitionID(src string) (string, error) { var declared struct { ID string `yaml:"id"` } if err := yaml.Unmarshal([]byte(src), &declared); err != nil { return "", fmt.Errorf("parse workflow YAML: %w", err) } if strings.TrimSpace(declared.ID) == "" { return "", fmt.Errorf("workflow id is required") } return declared.ID, nil } // PinnedDefinitionID returns the workflow id a task's definition pin declares, // checking the pin against its digest. ok is false when the task carries no // pin. This is the workflow the task's current run was compiled from, which is // what the run's own log names; the task's workflow column names the workflow // it runs next. func PinnedDefinitionID(t *Task) (string, bool, error) { if t.WorkflowDefinitionYAML == "" { return "", false, nil } if DigestDefinition(t.WorkflowDefinitionYAML) != t.WorkflowDefinitionDigest { return "", false, fmt.Errorf("stored workflow definition digest mismatch") } id, err := DefinitionID(t.WorkflowDefinitionYAML) if err != nil { return "", false, fmt.Errorf("stored workflow definition: %w", err) } return id, true, nil } // WorkflowDefinitionEntry and WorkflowDefinitionCollection are defined in // package task so dashboards can decode the stored projection without linking // the engine. Validation and compilation stay here. type ( WorkflowDefinitionEntry = task.WorkflowDefinitionEntry WorkflowDefinitionCollection = task.WorkflowDefinitionCollection ) // ValidateDefinitionCollection rejects malformed, duplicate, or mismatched // definitions, and every workflow.call step a definition carries: the callee // must exist, its inputs must be satisfiable, and the call graph must be // acyclic. func ValidateDefinitionCollection(collection WorkflowDefinitionCollection, registry StepRegistry) error { seen := make(map[string]struct{}, len(collection.Definitions)) parsed := make(map[string]YAMLDefinition, len(collection.Definitions)) for _, entry := range collection.Definitions { if _, ok := seen[entry.ID]; ok { return fmt.Errorf("duplicate workflow id %q", entry.ID) } seen[entry.ID] = struct{}{} definition, err := ParseDefinition(entry.YAML, registry) if err != nil { return err } if definition.ID != entry.ID { return fmt.Errorf("workflow entry id %q does not match YAML id %q", entry.ID, definition.ID) } parsed[entry.ID] = definition } if err := validateWorkflowCalls(parsed); err != nil { return err } return validateControlTargets(parsed) } // DecodeDefinitionCollection strictly decodes the control-plane projection. func DecodeDefinitionCollection(value []byte, registry StepRegistry) (WorkflowDefinitionCollection, error) { var collection WorkflowDefinitionCollection decoder := json.NewDecoder(bytes.NewReader(value)) decoder.DisallowUnknownFields() if err := decoder.Decode(&collection); err != nil { return WorkflowDefinitionCollection{}, err } if err := ValidateDefinitionCollection(collection, registry); err != nil { return WorkflowDefinitionCollection{}, err } return collection, nil } // ShippedDefinitions returns the restorable factory definitions. func ShippedDefinitions() WorkflowDefinitionCollection { return WorkflowDefinitionCollection{Definitions: shippedYAML()} } //go:embed shipped/*.yaml var shippedFiles embed.FS // shippedYAML is the shipped workflows written in the general step types. func shippedYAML() []WorkflowDefinitionEntry { files, _ := fs.Glob(shippedFiles, "shipped/*.yaml") entries := make([]WorkflowDefinitionEntry, 0, len(files)) for _, name := range files { data, err := shippedFiles.ReadFile(name) if err != nil { panic(err) // embedded at build time; unreadable means a broken binary } id := strings.TrimSuffix(path.Base(name), ".yaml") entries = append(entries, WorkflowDefinitionEntry{ID: id, YAML: string(data)}) } return entries } // branches is every list of steps nested in a step: its parallel branches or // its switch cases. func (step StepRecord) branches() map[string][]StepRecord { if step.Switch != nil { return step.Switch.Cases } return step.Parallel } // CheckModelAliases reports the first agent.run step in collection that names // a model alias aliases does not define. An empty alias means the default and // is resolved at dispatch. func CheckModelAliases(collection WorkflowDefinitionCollection, registry StepRegistry, aliases map[string]string) error { for _, entry := range collection.Definitions { definition, err := ParseDefinition(entry.YAML, registry) if err != nil { return err } if err := checkStepAliases(entry.ID, definition.Steps, aliases); err != nil { return err } } return nil } func checkStepAliases(workflowID string, steps []StepRecord, aliases map[string]string) error { for _, step := range steps { if step.Type == AgentRunStepName { var s agentRunSettings if err := step.Settings.Decode(&s); err != nil { return fmt.Errorf("workflow %q step %q: %w", workflowID, step.ID, err) } if s.Model != "" && aliases[s.Model] == "" { return fmt.Errorf("workflow %q step %q: model alias %q is not configured", workflowID, step.ID, s.Model) } } for _, branch := range step.Parallel { if err := checkStepAliases(workflowID, branch, aliases); err != nil { return err } } if step.Switch != nil { for _, branch := range step.Switch.Cases { if err := checkStepAliases(workflowID, branch, aliases); err != nil { return err } } } } return nil } // modelFreeStepTypes are the step types that never call a model. Any other // type counts as model use, so an unknown or new step keeps the credential // boundary. var modelFreeStepTypes = map[string]bool{ FinishStepName: true, HandoffStepName: true, ApproveStepName: true, CloseIssueStepName: true, CommentStepName: true, CommandRunStepName: true, WorkflowCallStepName: true, RepoPrepareStepName: true, RepoToolingStepName: true, RepoCommitStepName: true, RepoOpenPRStepName: true, GateRepositoryName: true, DiffRulesStepName: true, } // UsesModel reports whether a pinned definition has any step that may call a // model. A missing or undecodable definition counts as using one. func UsesModel(src string) bool { var definition YAMLDefinition if err := yaml.Unmarshal([]byte(src), &definition); err != nil || len(definition.Steps) == 0 { return true } return stepsUseModel(definition.Steps) } func stepsUseModel(steps []StepRecord) bool { for _, step := range steps { for _, branch := range step.Parallel { if stepsUseModel(branch) { return true } } if step.Switch != nil { for _, branch := range step.Switch.Cases { if stepsUseModel(branch) { return true } } } if step.Parallel == nil && step.Switch == nil && !modelFreeStepTypes[step.Type] { return true } } return false } // pushStepTypes are the steps that publish to the repository's forge. var pushStepTypes = []string{RepoCommitStepName, RepoOpenPRStepName} // DefinitionPushes reports whether a workflow definition has a step, at any // depth, that pushes to the repository. func DefinitionPushes(src string) bool { var doc any if yaml.Unmarshal([]byte(src), &doc) != nil { return false } return hasStepType(doc, pushStepTypes) } func hasStepType(node any, types []string) bool { switch n := node.(type) { case map[string]any: if t, ok := n["type"].(string); ok && slices.Contains(types, t) { return true } for _, v := range n { if hasStepType(v, types) { return true } } case []any: for _, v := range n { if hasStepType(v, types) { return true } } } return false }