From ca4b039cb4ceb126e706014bec3315cc92b352c7 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 13 Nov 2026 20:26:27 +1100 Subject: [PATCH] feat(workflow): serve step type titles with the step vocabulary (#1961) Each step type declares its title beside its factory and settings; the control plane serves it in x-step-types, and the dashboard reads it instead of a hand-written TYPE_TITLES table. Parallel and switch are YAML shapes, not registered types, so their titles stay with the graph. --- internal/domain/workflow/agent_run.go | 2 +- internal/domain/workflow/command_run.go | 2 +- internal/domain/workflow/control_steps.go | 8 ++--- internal/domain/workflow/diff_rules.go | 2 +- internal/domain/workflow/finish_step.go | 2 +- internal/domain/workflow/message_send.go | 2 +- internal/domain/workflow/repo_steps.go | 10 +++--- internal/domain/workflow/review_steps.go | 6 ++-- internal/domain/workflow/vocabulary.go | 32 +++++++++-------- internal/domain/workflow/workflow_call.go | 2 +- .../controlplanestore/controlplane.go | 2 +- .../controlplanestore/definitions.go | 4 +-- .../controlplanestore/workflow_definitions.go | 14 ++++---- ui/src/workflows/StepNode.vue | 6 ++-- ui/src/workflows/StepTypeItems.vue | 7 ++-- ui/src/workflows/WorkflowCanvas.vue | 6 ++-- ui/src/workflows/WorkflowEditor.vue | 2 +- ui/src/workflows/workflow-graph.ts | 36 ++++++------------- ui/src/workflows/workflow-yaml.ts | 2 ++ 19 files changed, 72 insertions(+), 75 deletions(-) diff --git a/internal/domain/workflow/agent_run.go b/internal/domain/workflow/agent_run.go index 59b455d97..85d292760 100644 --- a/internal/domain/workflow/agent_run.go +++ b/internal/domain/workflow/agent_run.go @@ -47,7 +47,7 @@ type agentRunSettings struct { // AgentRunStepType contributes the agent.run step type. func AgentRunStepType() StepType { - return StepType{Name: AgentRunStepName, Factory: newAgentRunStage, Settings: agentRunSettings{}} + return StepType{Name: AgentRunStepName, Title: "Agent", Factory: newAgentRunStage, Settings: agentRunSettings{}} } func newAgentRunStage(settings yaml.Node) (Stage, error) { diff --git a/internal/domain/workflow/command_run.go b/internal/domain/workflow/command_run.go index 07987d9af..d837c3d46 100644 --- a/internal/domain/workflow/command_run.go +++ b/internal/domain/workflow/command_run.go @@ -47,7 +47,7 @@ func (c commandRunCommand) command() agentrun.Command { // CommandRunStepType contributes the command.run step type. func CommandRunStepType() StepType { - return StepType{Name: CommandRunStepName, Factory: newCommandRunStage, Settings: commandRunSettings{}} + return StepType{Name: CommandRunStepName, Title: "Run commands", Factory: newCommandRunStage, Settings: commandRunSettings{}} } func newCommandRunStage(settings yaml.Node) (Stage, error) { diff --git a/internal/domain/workflow/control_steps.go b/internal/domain/workflow/control_steps.go index 7d60511f4..0c4590a62 100644 --- a/internal/domain/workflow/control_steps.go +++ b/internal/domain/workflow/control_steps.go @@ -26,10 +26,10 @@ const ( // ControlStepTypes contributes the control and forge step types. func ControlStepTypes() []StepType { return []StepType{ - {Name: HandoffStepName, Factory: newHandoffStage, Settings: handoffSettings{}}, - {Name: ApproveStepName, Factory: newApproveStage, Settings: approveSettings{}}, - {Name: CloseIssueStepName, Factory: newCloseIssueStage}, - {Name: CommentStepName, Factory: newCommentStage, Settings: commentSettings{}}, + {Name: HandoffStepName, Title: "Hand off", Factory: newHandoffStage, Settings: handoffSettings{}}, + {Name: ApproveStepName, Title: "Approval", Factory: newApproveStage, Settings: approveSettings{}}, + {Name: CloseIssueStepName, Title: "Close issue", Factory: newCloseIssueStage}, + {Name: CommentStepName, Title: "Comment", Factory: newCommentStage, Settings: commentSettings{}}, } } diff --git a/internal/domain/workflow/diff_rules.go b/internal/domain/workflow/diff_rules.go index ac7411fd0..b845915f6 100644 --- a/internal/domain/workflow/diff_rules.go +++ b/internal/domain/workflow/diff_rules.go @@ -79,7 +79,7 @@ type diffRulesSettings struct { // way the shipped stages are declared: the factory builds the stage the // executing side runs from the settings the validating side accepted. func DiffRulesStepType() StepType { - return StepType{Name: DiffRulesStepName, Factory: newDiffRulesStage, Settings: diffRulesSettings{}} + return StepType{Name: DiffRulesStepName, Title: "Diff rules", Factory: newDiffRulesStage, Settings: diffRulesSettings{}} } // newDiffRulesStage decodes and compiles the step's settings, refusing every diff --git a/internal/domain/workflow/finish_step.go b/internal/domain/workflow/finish_step.go index 2519f1af0..3c248300a 100644 --- a/internal/domain/workflow/finish_step.go +++ b/internal/domain/workflow/finish_step.go @@ -25,7 +25,7 @@ type finishSettings struct { // FinishStepType contributes the workflow.finish step type. func FinishStepType() StepType { - return StepType{Name: FinishStepName, Factory: newFinishStage, Settings: finishSettings{}} + return StepType{Name: FinishStepName, Title: "Finish", Factory: newFinishStage, Settings: finishSettings{}} } func newFinishStage(settings yaml.Node) (Stage, error) { diff --git a/internal/domain/workflow/message_send.go b/internal/domain/workflow/message_send.go index fcc09ed6b..fb0504e7c 100644 --- a/internal/domain/workflow/message_send.go +++ b/internal/domain/workflow/message_send.go @@ -26,7 +26,7 @@ type messageSendSettings struct { // MessageSendStepType contributes the message.send step type. func MessageSendStepType() StepType { - return StepType{Name: MessageSendStepName, Factory: newMessageSendStage, Settings: messageSendSettings{}} + return StepType{Name: MessageSendStepName, Title: "Send message", Factory: newMessageSendStage, Settings: messageSendSettings{}} } func newMessageSendStage(settings yaml.Node) (Stage, error) { diff --git a/internal/domain/workflow/repo_steps.go b/internal/domain/workflow/repo_steps.go index 8d5b746cc..a4973c8ed 100644 --- a/internal/domain/workflow/repo_steps.go +++ b/internal/domain/workflow/repo_steps.go @@ -25,11 +25,11 @@ const ( // RepoStepTypes contributes the general repository step types. func RepoStepTypes() []StepType { return []StepType{ - {Name: RepoPrepareStepName, Factory: newRepoPrepareStage, Settings: repoPrepareSettings{}}, - {Name: RepoToolingStepName, Factory: newRepoToolingStage}, - {Name: RepoCommitStepName, Factory: newRepoCommitStage, Settings: repoCommitSettings{}}, - {Name: RepoOpenPRStepName, Factory: newRepoOpenPRStage, Settings: repoOpenPRSettings{}}, - {Name: GateRepositoryName, Factory: newGateRepositoryStage, Settings: gateRepositorySettings{}}, + {Name: RepoPrepareStepName, Title: "Prepare worktree", Factory: newRepoPrepareStage, Settings: repoPrepareSettings{}}, + {Name: RepoToolingStepName, Title: "Install tooling", Factory: newRepoToolingStage}, + {Name: RepoCommitStepName, Title: "Commit", Factory: newRepoCommitStage, Settings: repoCommitSettings{}}, + {Name: RepoOpenPRStepName, Title: "Open pull request", Factory: newRepoOpenPRStage, Settings: repoOpenPRSettings{}}, + {Name: GateRepositoryName, Title: "Repository", Factory: newGateRepositoryStage, Settings: gateRepositorySettings{}}, } } diff --git a/internal/domain/workflow/review_steps.go b/internal/domain/workflow/review_steps.go index 8f6afe4e5..4240defd0 100644 --- a/internal/domain/workflow/review_steps.go +++ b/internal/domain/workflow/review_steps.go @@ -19,9 +19,9 @@ const ( // ReviewStepTypes contributes the review step types. func ReviewStepTypes() []StepType { return []StepType{ - {Name: ReviewPRStepName, Factory: newReviewPRStage, Settings: reviewPRSettings{}}, - {Name: ReviewRoundStepName, Factory: newReviewRoundStage}, - {Name: ReviewReplyStepName, Factory: newReviewReplyStage, Settings: reviewReplySettings{}}, + {Name: ReviewPRStepName, Title: "Review pull request", Factory: newReviewPRStage, Settings: reviewPRSettings{}}, + {Name: ReviewRoundStepName, Title: "Start review round", Factory: newReviewRoundStage}, + {Name: ReviewReplyStepName, Title: "Reply to review", Factory: newReviewReplyStage, Settings: reviewReplySettings{}}, } } diff --git a/internal/domain/workflow/vocabulary.go b/internal/domain/workflow/vocabulary.go index 81174f216..cef79862e 100644 --- a/internal/domain/workflow/vocabulary.go +++ b/internal/domain/workflow/vocabulary.go @@ -13,7 +13,9 @@ import ( // StepType is one named workflow step type: the vocabulary word a YAML // workflow names, plus the factory that builds its stage. type StepType struct { - Name string + Name string + // Title is the human name editors show for the step type. + Title string Factory StepFactory // Settings is a zero value of the step's settings type, from which the // control plane derives the settings schema editors build forms from. @@ -40,8 +42,9 @@ type Manager struct { mu sync.Mutex registry StepRegistry // owners maps each step type to the provider that registered it. - owners map[string]string - settings map[string]any + owners map[string]string + // types holds each registered step type's descriptor, for the control plane. + types map[string]StepType } // NewManager builds an empty family manager. It holds no vocabulary of its own: @@ -49,12 +52,12 @@ type Manager struct { // composition root, so the vocabulary every side resolves is the one that was // actually registered. func NewManager() *Manager { - return &Manager{registry: StepRegistry{}, owners: map[string]string{}, settings: map[string]any{}} + return &Manager{registry: StepRegistry{}, owners: map[string]string{}, types: map[string]StepType{}} } // Register validates a provider's whole contribution and applies all of it or // none. It refuses nil or unnamed providers, bad identifiers, missing -// factories, duplicates and types another provider already owns. +// factories or titles, duplicates and types another provider already owns. func (m *Manager) Register(provider StepTypeProvider) error { if lifecycle.IsNil(provider) { return errors.New("workflow step type provider is nil") @@ -65,8 +68,7 @@ func (m *Manager) Register(provider StepTypeProvider) error { } contributed := provider.StepTypes() - pending := make(StepRegistry, len(contributed)) - settings := make(map[string]any, len(contributed)) + pending := make(map[string]StepType, len(contributed)) order := make([]string, 0, len(contributed)) for _, stepType := range contributed { switch { @@ -74,12 +76,13 @@ func (m *Manager) Register(provider StepTypeProvider) error { return fmt.Errorf("workflow step type provider %q: step type %q is not a stable identifier", name, stepType.Name) case stepType.Factory == nil: return fmt.Errorf("workflow step type provider %q: step type %q has no factory", name, stepType.Name) + case stepType.Title == "": + return fmt.Errorf("workflow step type provider %q: step type %q has no title", name, stepType.Name) } if _, declared := pending[stepType.Name]; declared { return fmt.Errorf("workflow step type provider %q declares step type %q twice", name, stepType.Name) } - pending[stepType.Name] = stepType.Factory - settings[stepType.Name] = stepType.Settings + pending[stepType.Name] = stepType order = append(order, stepType.Name) } @@ -91,8 +94,8 @@ func (m *Manager) Register(provider StepTypeProvider) error { } } for _, stepType := range order { - m.registry[stepType] = pending[stepType] - m.settings[stepType] = settings[stepType] + m.registry[stepType] = pending[stepType].Factory + m.types[stepType] = pending[stepType] m.owners[stepType] = name } return nil @@ -109,10 +112,9 @@ func (m *Manager) Registry() StepRegistry { return registry } -// Settings returns each registered step type's settings value (see -// StepType.Settings), keyed by type name. -func (m *Manager) Settings() map[string]any { +// Types returns each registered step type's descriptor, keyed by type name. +func (m *Manager) Types() map[string]StepType { m.mu.Lock() defer m.mu.Unlock() - return maps.Clone(m.settings) + return maps.Clone(m.types) } diff --git a/internal/domain/workflow/workflow_call.go b/internal/domain/workflow/workflow_call.go index 6a9c32f50..0fbf59a96 100644 --- a/internal/domain/workflow/workflow_call.go +++ b/internal/domain/workflow/workflow_call.go @@ -71,7 +71,7 @@ var refName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`) // WorkflowCallStepType contributes the workflow.call step type. func WorkflowCallStepType() StepType { - return StepType{Name: WorkflowCallStepName, Factory: newWorkflowCallStage, Settings: workflowCallSettings{}} + return StepType{Name: WorkflowCallStepName, Title: "Call workflow", Factory: newWorkflowCallStage, Settings: workflowCallSettings{}} } func newWorkflowCallStage(settings yaml.Node) (Stage, error) { diff --git a/internal/infrastructure/controlplanestore/controlplane.go b/internal/infrastructure/controlplanestore/controlplane.go index dc4545e14..7c71f7697 100644 --- a/internal/infrastructure/controlplanestore/controlplane.go +++ b/internal/infrastructure/controlplanestore/controlplane.go @@ -63,7 +63,7 @@ func NewServer(resources ResourceStore, steps *workflow.Manager) (*Server, error if err != nil { return nil, err } - definitions := builtinDefinitions(registry, steps.Settings()) + definitions := builtinDefinitions(registry, steps.Types()) byKind := make(map[string]Definition, len(definitions)) for _, definition := range definitions { byKind[definition.Kind] = definition diff --git a/internal/infrastructure/controlplanestore/definitions.go b/internal/infrastructure/controlplanestore/definitions.go index e5018711d..f4b9150b0 100644 --- a/internal/infrastructure/controlplanestore/definitions.go +++ b/internal/infrastructure/controlplanestore/definitions.go @@ -7,8 +7,8 @@ import ( // Schemas are not declared here: each Definition names its document type, and // Definition.Descriptor derives the JSON Schema from it (internal/infrastructure/controlplanestore/schema.go). -func builtinDefinitions(steps workflow.StepRegistry, settings map[string]any) []Definition { - definitions := []Definition{taskPolicyDefinition(), workflowDefinition(), workflowDefinitionsDefinition(steps, settings), workflowDraftsDefinition(), workflowEnablementDefinition(), curatorDefinition(), soulDefinition(), agentProfileDefinition(), playbooksDefinition(), skillsDefinition(), credentialBindingsDefinition(), identityGrantsDefinition(), orgModelPolicyDefinition(), forgeConnectionsDefinition()} +func builtinDefinitions(steps workflow.StepRegistry, types map[string]workflow.StepType) []Definition { + definitions := []Definition{taskPolicyDefinition(), workflowDefinition(), workflowDefinitionsDefinition(steps, types), workflowDraftsDefinition(), workflowEnablementDefinition(), curatorDefinition(), soulDefinition(), agentProfileDefinition(), playbooksDefinition(), skillsDefinition(), credentialBindingsDefinition(), identityGrantsDefinition(), orgModelPolicyDefinition(), forgeConnectionsDefinition()} definitions = append(definitions, modelDefinitions()...) definitions = append(definitions, operationalDefinitions()...) return definitions diff --git a/internal/infrastructure/controlplanestore/workflow_definitions.go b/internal/infrastructure/controlplanestore/workflow_definitions.go index cc524b97e..5236ef7a5 100644 --- a/internal/infrastructure/controlplanestore/workflow_definitions.go +++ b/internal/infrastructure/controlplanestore/workflow_definitions.go @@ -21,7 +21,7 @@ func stepRegistry(steps *workflow.Manager) (workflow.StepRegistry, error) { return steps.Registry(), nil } -func workflowDefinitionsDefinition(steps workflow.StepRegistry, settings map[string]any) Definition { +func workflowDefinitionsDefinition(steps workflow.StepRegistry, types map[string]workflow.StepType) Definition { return Definition{ Kind: WorkflowDefinitionsKind, Title: "Workflow definitions", @@ -45,18 +45,18 @@ func workflowDefinitionsDefinition(steps workflow.StepRegistry, settings map[str value, err := json.Marshal(collection) return value, removed, err }, - SchemaExtensions: map[string]any{"x-step-types": stepTypeVocabulary(steps, settings), "x-intake-routes": workflow.IntakeRoutes()}, + SchemaExtensions: map[string]any{"x-step-types": stepTypeVocabulary(steps, types), "x-intake-routes": workflow.IntakeRoutes()}, } } // stepTypeVocabulary is the registered step types as the dashboard editor -// reads them: each name, whether it needs a repository, and the schema of its -// settings (absent for a step that takes none). -func stepTypeVocabulary(steps workflow.StepRegistry, settings map[string]any) []map[string]any { +// reads them: each name, title, whether it needs a repository, and the schema +// of its settings (absent for a step that takes none). +func stepTypeVocabulary(steps workflow.StepRegistry, types map[string]workflow.StepType) []map[string]any { vocabulary := make([]map[string]any, 0, len(steps)) for _, name := range slices.Sorted(maps.Keys(steps)) { - entry := map[string]any{"name": name, "needs_repository": workflow.NeedsRepository(name)} - if schema := settingsSchema(settings[name]); schema != nil { + entry := map[string]any{"name": name, "title": types[name].Title, "needs_repository": workflow.NeedsRepository(name)} + if schema := settingsSchema(types[name].Settings); schema != nil { entry["settings"] = schema } vocabulary = append(vocabulary, entry) diff --git a/ui/src/workflows/StepNode.vue b/ui/src/workflows/StepNode.vue index 119a2ff16..0d453efce 100644 --- a/ui/src/workflows/StepNode.vue +++ b/ui/src/workflows/StepNode.vue @@ -7,6 +7,7 @@ import { CircleAlert, CircleCheck, CircleMinus, CircleX, EllipsisVertical, Flag, import { Button } from "@/components/ui/button"; import { Input } from "@/components/ui/input"; import { duration } from "@/lib/format"; +import { useWorkflowsStore } from "@/stores/workflows"; import { stepIcon } from "./step-icons"; import { stepTitle, type StepNodeData } from "./workflow-graph"; @@ -72,10 +73,11 @@ const status = computed(() => { return null; }); +const workflows = useWorkflowsStore(); const badge = computed(() => { if (props.data.kind === "start") return { icon: Play, label: "Trigger" }; if (props.data.kind === "workflow") return { icon: Settings2, label: "Workflow" }; - return { icon: stepIcon(props.data.type), label: stepTitle(props.data.type) }; + return { icon: stepIcon(props.data.type), label: stepTitle(props.data.type, workflows.stepTypes) }; }); const number = computed(() => (props.data.step ? `${Number(props.data.step)}.` : "")); @@ -150,7 +152,7 @@ function commitRename(event: Event): void { :model-value="data.name ?? ''" class="nodrag nopan h-6 px-1 text-label" aria-label="Step id" - :placeholder="stepTitle(data.type)" + :placeholder="stepTitle(data.type, workflows.stepTypes)" @click.stop @keydown.enter.prevent="commitRename" @keydown.esc="renaming = false; data.onRenameDone?.()" diff --git a/ui/src/workflows/StepTypeItems.vue b/ui/src/workflows/StepTypeItems.vue index cdd76e59f..d15779ca8 100644 --- a/ui/src/workflows/StepTypeItems.vue +++ b/ui/src/workflows/StepTypeItems.vue @@ -8,6 +8,7 @@ import { DropdownMenuSubContent, DropdownMenuSubTrigger, } from "@/components/ui/dropdown-menu"; +import { useWorkflowsStore } from "@/stores/workflows"; import { stepGroups } from "./step-icons"; import { stepTitle } from "./workflow-graph"; @@ -15,6 +16,8 @@ const props = defineProps<{ types: string[] }>(); const emit = defineEmits<{ pick: [string] }>(); const groups = computed(() => stepGroups(props.types)); +const workflows = useWorkflowsStore(); +const titleOf = (type: string) => stepTitle(type, workflows.stepTypes);