feat(api): add ListStageSummaries and WatchStageSummaries RPCs

api/service/v1alpha1/service.proto

@@ -5,6 +5,7 @@ package akuity.io.kargo.service.v1alpha1;
 import "google/protobuf/timestamp.proto";
 import "api/v1alpha1/generated.proto";
 import "k8s.io/api/core/v1/generated.proto";
+import "k8s.io/apimachinery/pkg/apis/meta/v1/generated.proto";
 import "api/stubs/rollouts/v1alpha1/generated.proto";
 import "api/rbac/v1alpha1/generated.proto";
 import "google/protobuf/any.proto";
@@ -52,12 +53,27 @@ service KargoService {
 
   // ListStages retrieves all stages within a project.
   rpc ListStages(ListStagesRequest) returns (ListStagesResponse);
+  // ListStageSummaries retrieves a lightweight projection of Stages within a
+  // project, containing only the fields typically required to render list
+  // and graph views. Use GetStage to retrieve the full Stage resource when
+  // detail-level fields are needed.
+  rpc ListStageSummaries(ListStageSummariesRequest) returns (ListStageSummariesResponse);
   // ListImages returns available images and their usage across stages.
   rpc ListImages(ListImagesRequest) returns (ListImagesResponse);
   // GetStage retrieves details of a specific stage.
   rpc GetStage(GetStageRequest) returns (GetStageResponse);
+  // GetStageHealthOutputs returns the raw health output blob for the
+  // specified Stages in a project. Intended for clients that use
+  // ListStageSummaries for the list and need to resolve per-argocd-app
+  // health only for the Stages currently in viewport. Stages that do not
+  // exist or have no health output recorded are omitted from the response.
+  rpc GetStageHealthOutputs(GetStageHealthOutputsRequest) returns (GetStageHealthOutputsResponse);
   // WatchStages provides a streaming interface to monitor stage changes.
   rpc WatchStages(WatchStagesRequest) returns (stream WatchStagesResponse);
+  // WatchStageSummaries provides a streaming interface to monitor stage
+  // changes, returning the same lightweight projection as
+  // ListStageSummaries for each event.
+  rpc WatchStageSummaries(WatchStageSummariesRequest) returns (stream WatchStageSummariesResponse);
   // DeleteStage removes a stage from the system.
   rpc DeleteStage(DeleteStageRequest) returns (DeleteStageResponse);
 
@@ -505,6 +521,24 @@ message GetStageResponse {
   }
 }
 
+// GetStageHealthOutputsRequest is the request for fetching the raw health
+// output blob of one or more Stages within a project.
+message GetStageHealthOutputsRequest {
+  // project is the name of the project containing the Stages.
+  string project = 1;
+  // stage_names is the list of Stage names whose health outputs to return.
+  // Order is irrelevant; duplicates are deduplicated by the server.
+  repeated string stage_names = 2 [json_name = "stageNames"];
+}
+
+// GetStageHealthOutputsResponse contains per-Stage raw health output blobs.
+message GetStageHealthOutputsResponse {
+  // health_outputs maps Stage name to the raw bytes of its
+  // Stage.status.health.output.raw field. Stages that do not exist in the
+  // project or have no health output recorded are omitted from the map.
+  map<string, bytes> health_outputs = 1 [json_name = "healthOutputs"];
+}
+
 // WatchStagesRequest is the request for watching stage changes via streaming.
 message WatchStagesRequest {
   // project is the name of the project whose stages should be watched.
@@ -533,6 +567,110 @@ message DeleteStageRequest {
 message DeleteStageResponse {
   /* explicitly empty */
 }
+
+// StageSummary is a lightweight projection of a Stage resource intended for
+// use by clients rendering list or graph views of many stages. It omits
+// heavy fields that are only needed when a single stage is inspected in
+// detail (e.g. full FreightHistory beyond the current FreightCollection,
+// PromotionTemplate step configuration, and Verification configuration).
+message StageSummary {
+  // metadata contains the Stage's identity and Kubernetes object metadata.
+  optional .k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
+  // spec contains the subset of StageSpec fields needed by list/graph views.
+  optional StageSpecSummary spec = 2;
+  // status contains the subset of StageStatus fields needed by list/graph views.
+  optional StageStatusSummary status = 3;
+}
+
+// StageSpecSummary is the subset of StageSpec fields returned by
+// ListStageSummaries. See StageSummary for the motivation.
+message StageSpecSummary {
+  // shard is the name of the shard that the Stage belongs to, mirroring
+  // StageSpec.shard.
+  string shard = 1;
+  // requestedFreight mirrors StageSpec.requestedFreight. This is needed in
+  // full to render graph edges between Stages and their upstream sources.
+  repeated github.com.akuity.kargo.api.v1alpha1.FreightRequest requested_freight = 2;
+  // promotionStepCount is the number of promotion steps defined in the
+  // Stage's PromotionTemplate, or zero if no PromotionTemplate is defined.
+  // Use GetStage to retrieve the full step configuration.
+  int32 promotion_step_count = 3;
+  // hasVerification indicates whether the Stage defines a Verification.
+  // Use GetStage to retrieve the full Verification configuration.
+  bool has_verification = 4;
+}
+
+// StageStatusSummary is the subset of StageStatus fields returned by
+// ListStageSummaries. See StageSummary for the motivation.
+message StageStatusSummary {
+  // conditions mirrors StageStatus.conditions.
+  repeated .k8s.io.apimachinery.pkg.apis.meta.v1.Condition conditions = 1;
+  // lastHandledRefresh mirrors StageStatus.lastHandledRefresh.
+  string last_handled_refresh = 2;
+  // currentFreight is the FreightCollection currently deployed to the Stage
+  // (i.e. index 0 of StageStatus.freightHistory), or null if no Freight has
+  // been deployed. Use GetStage to retrieve the full FreightHistory.
+  optional github.com.akuity.kargo.api.v1alpha1.FreightCollection current_freight = 3;
+  // currentPromotion mirrors StageStatus.currentPromotion.
+  optional github.com.akuity.kargo.api.v1alpha1.PromotionReference current_promotion = 4;
+  // lastPromotion mirrors StageStatus.lastPromotion.
+  optional github.com.akuity.kargo.api.v1alpha1.PromotionReference last_promotion = 5;
+  // health mirrors StageStatus.health.
+  optional github.com.akuity.kargo.api.v1alpha1.Health health = 6;
+  // observedGeneration mirrors StageStatus.observedGeneration.
+  int64 observed_generation = 7;
+  // autoPromotionEnabled mirrors StageStatus.autoPromotionEnabled.
+  bool auto_promotion_enabled = 8;
+}
+
+// ListStageSummariesRequest is the request for listing stage summaries
+// within a project.
+message ListStageSummariesRequest {
+  // project is the name of the project whose stage summaries should be listed.
+  string project = 1;
+  // freightOrigins is an optional list of Warehouse names. When non-empty,
+  // only Stages that request Freight originating from at least one of the
+  // named Warehouses (directly or transitively via upstream Stages) will be
+  // returned. Mirrors ListStagesRequest.freightOrigins.
+  repeated string freight_origins = 2;
+}
+
+// ListStageSummariesResponse contains a list of stage summaries within a project.
+message ListStageSummariesResponse {
+  // stageSummaries is the list of StageSummary objects found in the project.
+  repeated StageSummary stage_summaries = 1;
+  // resourceVersion is the Kubernetes ResourceVersion of the underlying
+  // StageList. Clients may pass this value to WatchStageSummaries to begin
+  // watching from the exact point this list was taken, receiving only
+  // subsequent changes without redundant initial events.
+  string resource_version = 2;
+}
+
+// WatchStageSummariesRequest is the request for watching stage summaries via streaming.
+message WatchStageSummariesRequest {
+  // project is the name of the project whose stage summaries should be watched.
+  string project = 1;
+  // name is the name of a specific stage to watch, if empty all stages in the project are watched.
+  string name = 2;
+  // freightOrigins is an optional list of Warehouse names. When non-empty,
+  // only events for Stages that request Freight originating from at least
+  // one of the named Warehouses (directly or transitively via upstream
+  // Stages) will be streamed. Mirrors WatchStagesRequest.freightOrigins.
+  repeated string freight_origins = 3;
+  // resourceVersion is an optional Kubernetes ResourceVersion. When set,
+  // the watch begins at the specified version, allowing clients to resume
+  // from a prior list or watch without missing or duplicating events.
+  string resource_version = 4;
+}
+
+// WatchStageSummariesResponse contains stage summary change notifications.
+message WatchStageSummariesResponse {
+  // stageSummary is the StageSummary for the Stage that changed.
+  optional StageSummary stage_summary = 1;
+  // type indicates the type of change (ADDED, MODIFIED, DELETED).
+  string type = 2;
+}
+
 /* ClusterConfig Messages */
 
 message GetClusterConfigRequest {