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.
This commit is contained in:
sam committed 2026-11-13 20:26:27 +11:00
1 parent 841c6aea16
commit ca4b039cb4
19 files changed
+72 -75

No files matched your search

+1 -1
View File
@@ -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) {
+1 -1
View File
@@ -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) {
+4 -4
View File
@@ -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{}},
}
}
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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) {
+1 -1
View File
@@ -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) {
+5 -5
View File
@@ -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{}},
}
}
+3 -3
View File
@@ -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{}},
}
}
+17 -15
View File
@@ -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)
}
+1 -1
View File
@@ -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) {
@@ -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
@@ -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
@@ -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)
+4 -2
View File
@@ -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?.()"
+5 -2
View File
@@ -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);
</script>
<template>
@@ -24,7 +27,7 @@ const groups = computed(() => stepGroups(props.types));
<!-- A group of one is its step: no submenu to open for a single choice. -->
<DropdownMenuItem v-if="group.types.length === 1" @select="emit('pick', group.types[0])">
<component :is="group.icon" />
{{ stepTitle(group.types[0]) }}
{{ titleOf(group.types[0]) }}
</DropdownMenuItem>
<DropdownMenuSub v-else>
<DropdownMenuSubTrigger>
@@ -33,7 +36,7 @@ const groups = computed(() => stepGroups(props.types));
</DropdownMenuSubTrigger>
<DropdownMenuSubContent class="w-52">
<DropdownMenuItem v-for="type in group.types" :key="type" @select="emit('pick', type)">
{{ stepTitle(type) }}
{{ titleOf(type) }}
</DropdownMenuItem>
</DropdownMenuSubContent>
</DropdownMenuSub>
+4 -2
View File
@@ -3,6 +3,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip
import { computed, nextTick, ref, watch } from "vue";
import { Handle, Position, VueFlow, type NodeMouseEvent, type VueFlowStore } from "@vue-flow/core";
import { Background } from "@vue-flow/background";
import { useWorkflowsStore } from "@/stores/workflows";
import { useMediaQuery, usePreferredReducedMotion, useResizeObserver, useTransition } from "@vueuse/core";
import { ArrowDown, ArrowUp, Copy, GitBranch, Maximize, Minus, Pencil, Plus, RotateCcw, Split, Trash2 } from "@lucide/vue";
import "@vue-flow/core/dist/style.css";
@@ -69,8 +70,9 @@ const keyOf = (data: StepNodeData) => (data.kind === "step" ? JSON.stringify(dat
const container = ref<HTMLElement | null>(null);
const viewport = ref<HTMLElement | null>(null);
const phone = useMediaQuery("(max-width: 767px)");
const workflows = useWorkflowsStore();
const graph = computed(() => {
const laid = withRuns(workflowGraph(props.yaml), props.stages ?? []);
const laid = withRuns(workflowGraph(props.yaml, workflows.stepTypes), props.stages ?? []);
if (!props.types?.length) return laid;
// Workflow-wide settings sit on a card above the trigger.
const workflow: GraphNode = { id: "workflow", type: "step", position: { x: 0, y: TOP }, data: { kind: "workflow", key: "workflow", title: "Settings", type: "", detail: props.summary ?? "" } };
@@ -382,7 +384,7 @@ const beforePath = computed(() => menuPath.value ? [...menuPath.value.slice(0, -
</DropdownMenuTrigger>
<DropdownMenuContent class="w-56" align="start">
<template v-if="menu.step?.kind === 'step' && menuPath">
<DropdownMenuLabel class="truncate">{{ menu.step.title || stepTitle(menu.step.type) }}</DropdownMenuLabel>
<DropdownMenuLabel class="truncate">{{ menu.step.title || stepTitle(menu.step.type, workflows.stepTypes) }}</DropdownMenuLabel>
<template v-if="restart">
<DropdownMenuItem :disabled="restart.blocked" @select="emit('restart', restart.from)"><RotateCcw />{{ restart.label }}</DropdownMenuItem>
<DropdownMenuSeparator />
+1 -1
View File
@@ -91,7 +91,7 @@ const unpinned = computed(() => Boolean(watchedRun.value && !watchedRun.value.wo
const drawnStages = computed(() => unpinned.value ? [] : stages.value);
const pinnedYaml = computed(() => watchedRun.value?.workflow_definition_yaml);
const canvasYaml = computed(() => pinnedYaml.value || yaml.value);
const graph = computed(() => withRuns(workflowGraph(canvasYaml.value), drawnStages.value));
const graph = computed(() => withRuns(workflowGraph(canvasYaml.value, workflows.stepTypes), drawnStages.value));
function toggle(key: string): void {
open.value = open.value === key ? null : key;
const run = graph.value.nodes.find((node) => JSON.stringify(node.data.path ?? null) === open.value)?.data.run;
+11 -25
View File
@@ -2,6 +2,7 @@ import { parseDocument } from "yaml";
import { branchingOf } from "./workflow-edit.ts";
import type { WorkflowTrigger } from "./workflow-triggers";
import type { StepTypeInfo } from "./workflow-yaml.ts";
/**
* A workflow definition laid out as a graph: a start node, each step as a
@@ -146,30 +147,15 @@ export interface WorkflowGraph {
const ROW = 140;
const COLUMN = 280;
const TYPE_TITLES: Record<string, string> = {
parallel: "Parallel",
switch: "Switch",
"agent.run": "Agent",
"command.run": "Run commands",
"repo.prepare": "Prepare worktree",
"repo.commit": "Commit",
"repo.open-pr": "Open pull request",
"gate.repository": "Repository",
"gate.diff-rules": "Diff rules",
"forge.comment": "Comment",
"forge.close-issue": "Close issue",
"workflow.approve": "Approval",
"workflow.call": "Call workflow",
"workflow.handoff": "Hand off",
"workflow.finish": "Finish",
"review.pr": "Review pull request",
"review.start-round": "Start review round",
"review.reply": "Reply to review",
};
// Parallel and switch are YAML shapes, not registered step types, so the server
// does not title them.
const BRANCH_TITLES: Record<"parallel" | "switch", string> = { parallel: "Parallel", switch: "Switch" };
/** A step type's display name: a known one's title, else the type itself. */
export function stepTitle(type: string): string {
return TYPE_TITLES[type] ?? type;
/** A step type's display name: the title the server serves for it, else the type
* itself, so a vocabulary that has not loaded shows the raw name. */
export function stepTitle(type: string, vocabulary: readonly StepTypeInfo[]): string {
if (type === "parallel" || type === "switch") return BRANCH_TITLES[type];
return vocabulary.find((step) => step.name === type)?.title ?? type;
}
const REFERENCE = /\{\{\s*steps\.([A-Za-z0-9_-]+)\.[^}]*\}\}/g;
@@ -224,7 +210,7 @@ function referencedSteps(settings: unknown, when: unknown): string[] {
return [...new Set([...text.matchAll(REFERENCE)].map((match) => match[1]))];
}
export function workflowGraph(source: string): WorkflowGraph {
export function workflowGraph(source: string, vocabulary: readonly StepTypeInfo[] = []): WorkflowGraph {
const value: unknown = parseDocument(source).toJS();
const steps = isMapping(value) && Array.isArray(value.steps) ? value.steps : [];
const nodes: GraphNode[] = [];
@@ -276,7 +262,7 @@ export function workflowGraph(source: string): WorkflowGraph {
kind: "step",
key: stepID || key,
name: stepID || undefined,
title: stepID || stepTitle(type),
title: stepID || stepTitle(type, vocabulary),
type,
step: path?.length === 2 ? String(Number(path[1]) + 1).padStart(2, "0") : undefined,
detail: branching?.on ? `on ${branching.on.replace(/^steps\./, "")}` : stepDetail(type, settings),
+2
View File
@@ -28,6 +28,8 @@ export interface SettingsSchema {
/** One registered step type, as the control-plane catalog serves it. */
export interface StepTypeInfo {
name: string;
/** The name editors show for the step type. */
title: string;
needs_repository: boolean;
/** Absent for a step that takes no settings. */
settings?: SettingsSchema;