fix: sort required arrays in spec-patch to stabilize Spec Freshness CI

swag init --requiredByDefault generates required[] in struct field
declaration order, but the committed swagger artifacts have them in
alphabetical order (hand-edited across earlier PR commits). The
git diff --exit-code check in the Spec Freshness job therefore
always fails, because the regenerated arrays differ in element order
even though the content is identical.

Fix: append
  | .definitions |= with_entries(.value.required |= if . then sort else . end)
to both the jq (swagger.json) and yq (swagger.yaml) spec-patch filters.
This normalises every required[] to alphabetical order after every swag
run, making spec-patch idempotent regardless of struct field ordering.

Author: michaelmcnees

packages/engine/Makefile

@@ -41,11 +41,13 @@ spec: ## Regenerate OpenAPI spec (requires: go install github.com/swaggo/swag/cm
 spec-patch: ## Re-apply manual OpenAPI patches lost on swag regeneration
 	@# swag init does not emit global security declarations, per-operation security
 	@# overrides, additionalProperties on free-form objects, or RFC 3339/date format
-	@# annotations on timestamp fields. Patch them back after every regeneration run.
+	@# annotations on timestamp fields. Also normalises required[] to alphabetical
+	@# order (swag emits them in struct field order; we keep them sorted for stable
+	@# diffs). Patch them back after every regeneration run.
 	@# Requires jq and yq (pip install yq).
-	jq --indent 4 --ascii-output '.security=[{"ApiKeyAuth":[]},{"OIDCAuth":[]}]|.paths["/healthz"].get.security=[]|.paths["/readyz"].get.security=[]|.definitions["server.WorkflowDetailResponse"].properties.definition.additionalProperties=true|.definitions["server.UsageResponse"].properties.period_start.format="date"|.definitions["server.ExecutionDetail"].properties.started_at.format="date-time"|.definitions["server.ExecutionDetail"].properties.completed_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.started_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.completed_at.format="date-time"|.definitions["server.StepSummary"].properties.started_at.format="date-time"|.definitions["server.StepSummary"].properties.completed_at.format="date-time"|.definitions["workflow.VersionSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.updated_at.format="date-time"' \
+	jq --indent 4 --ascii-output '.security=[{"ApiKeyAuth":[]},{"OIDCAuth":[]}]|.paths["/healthz"].get.security=[]|.paths["/readyz"].get.security=[]|.definitions["server.WorkflowDetailResponse"].properties.definition.additionalProperties=true|.definitions["server.UsageResponse"].properties.period_start.format="date"|.definitions["server.ExecutionDetail"].properties.started_at.format="date-time"|.definitions["server.ExecutionDetail"].properties.completed_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.started_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.completed_at.format="date-time"|.definitions["server.StepSummary"].properties.started_at.format="date-time"|.definitions["server.StepSummary"].properties.completed_at.format="date-time"|.definitions["workflow.VersionSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.updated_at.format="date-time"|.definitions|=with_entries(.value.required|=if . then sort else . end)' \
 	  internal/server/docs/swagger.json > internal/server/docs/swagger.json.tmp && \
 	  mv internal/server/docs/swagger.json.tmp internal/server/docs/swagger.json
-	yq -y '.security=[{"ApiKeyAuth":[]},{"OIDCAuth":[]}]|.paths["/healthz"].get.security=[]|.paths["/readyz"].get.security=[]|.definitions["server.WorkflowDetailResponse"].properties.definition.additionalProperties=true|.definitions["server.UsageResponse"].properties.period_start.format="date"|.definitions["server.ExecutionDetail"].properties.started_at.format="date-time"|.definitions["server.ExecutionDetail"].properties.completed_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.started_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.completed_at.format="date-time"|.definitions["server.StepSummary"].properties.started_at.format="date-time"|.definitions["server.StepSummary"].properties.completed_at.format="date-time"|.definitions["workflow.VersionSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.updated_at.format="date-time"' \
+	yq -y '.security=[{"ApiKeyAuth":[]},{"OIDCAuth":[]}]|.paths["/healthz"].get.security=[]|.paths["/readyz"].get.security=[]|.definitions["server.WorkflowDetailResponse"].properties.definition.additionalProperties=true|.definitions["server.UsageResponse"].properties.period_start.format="date"|.definitions["server.ExecutionDetail"].properties.started_at.format="date-time"|.definitions["server.ExecutionDetail"].properties.completed_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.started_at.format="date-time"|.definitions["server.ExecutionSummary"].properties.completed_at.format="date-time"|.definitions["server.StepSummary"].properties.started_at.format="date-time"|.definitions["server.StepSummary"].properties.completed_at.format="date-time"|.definitions["workflow.VersionSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.created_at.format="date-time"|.definitions["workflow.WorkflowSummary"].properties.updated_at.format="date-time"|.definitions|=with_entries(.value.required|=if . then sort else . end)' \
 	  internal/server/docs/swagger.yaml > internal/server/docs/swagger.yaml.tmp && \
 	  mv internal/server/docs/swagger.yaml.tmp internal/server/docs/swagger.yaml