feat(sandbox): add label selectors to template listing

Signed-off-by: Gordon Sim <gsim@redhat.com>

Author: grs

.agents/skills/openshell-cli/SKILL.md

@@ -286,6 +286,7 @@ openshell sandbox template create gpu-kata \
   --label team=runtime \
   --env FEATURE_FLAG=on
 openshell sandbox template list
+openshell sandbox template list --label-selector team=runtime
 openshell sandbox template list --all-workspaces --output json
 openshell sandbox template get gpu-kata
 openshell sandbox template delete gpu-kata

.agents/skills/openshell-cli/cli-reference.md

@@ -285,6 +285,7 @@ List sandbox workload templates.
 |------|---------|-------------|
 | `--limit <N>` | 100 | Maximum templates |
 | `--offset <N>` | 0 | Pagination offset |
+| `--label-selector <KEY=VALUE,...>` | empty | Filter templates by labels |
 | `--names` | false | Print only template names |
 | `--all-workspaces` | false | List templates across all workspaces; requires platform-admin permissions |
 | `--output table|yaml|json` | `table` | Output format |

crates/openshell-cli/src/main.rs

@@ -1800,6 +1800,10 @@ enum SandboxTemplateCommands {
         #[arg(long, default_value_t = 0)]
         offset: u32,
 
+        /// Filter templates by labels, e.g. env=prod,team=runtime.
+        #[arg(long)]
+        label_selector: Option<String>,
+
         /// Print only template names (one per line).
         #[arg(long, conflicts_with = "output")]
         names: bool,
@@ -3464,6 +3468,7 @@ async fn run_async() -> Result<()> {
                             SandboxTemplateCommands::List {
                                 limit,
                                 offset,
+                                label_selector,
                                 names,
                                 output,
                                 all_workspaces,
@@ -3472,6 +3477,7 @@ async fn run_async() -> Result<()> {
                                     endpoint,
                                     limit,
                                     offset,
+                                    label_selector.as_deref(),
                                     names,
                                     output.as_str(),
                                     &cli.workspace,
@@ -5666,6 +5672,8 @@ mod tests {
             "list",
             "--names",
             "--all-workspaces",
+            "--label-selector",
+            "team=runtime",
             "--limit",
             "25",
             "--offset",
@@ -5679,6 +5687,7 @@ mod tests {
                     Some(SandboxCommands::Template(SandboxTemplateCommands::List {
                         limit,
                         offset,
+                        label_selector,
                         names,
                         all_workspaces,
                         ..
@@ -5687,6 +5696,7 @@ mod tests {
             }) => {
                 assert_eq!(limit, 25);
                 assert_eq!(offset, 5);
+                assert_eq!(label_selector.as_deref(), Some("team=runtime"));
                 assert!(names);
                 assert!(all_workspaces);
             }

crates/openshell-cli/src/run.rs

@@ -2553,6 +2553,7 @@ pub async fn sandbox_template_list(
     server: &str,
     limit: u32,
     offset: u32,
+    label_selector: Option<&str>,
     names_only: bool,
     output: &str,
     workspace: &str,
@@ -2570,6 +2571,7 @@ pub async fn sandbox_template_list(
                 workspace.to_string()
             },
             all_workspaces,
+            label_selector: label_selector.unwrap_or_default().to_string(),
         })
         .await
         .into_diagnostic()?;

crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs

@@ -1684,6 +1684,7 @@ async fn sandbox_template_list_and_delete_send_workspace_requests() {
         &server.endpoint,
         25,
         5,
+        Some("team=runtime"),
         false,
         "table",
         "default",
@@ -1702,6 +1703,7 @@ async fn sandbox_template_list_and_delete_send_workspace_requests() {
         .expect("template list request should be recorded");
     assert_eq!(list_request.limit, 25);
     assert_eq!(list_request.offset, 5);
+    assert_eq!(list_request.label_selector, "team=runtime");
     assert_eq!(list_request.workspace, "default");
     assert!(!list_request.all_workspaces);
 

crates/openshell-sdk/src/client.rs

@@ -221,6 +221,7 @@ impl OpenShellClient {
                     offset: opts.offset,
                     workspace: String::new(),
                     all_workspaces: opts.all_workspaces,
+                    label_selector: opts.label_selector.clone(),
                 };
                 async move { grpc.list_sandbox_templates(request).await }
             })
@@ -708,6 +709,7 @@ impl WorkspaceScopedClient {
                         self.workspace.clone()
                     },
                     all_workspaces: opts.all_workspaces,
+                    label_selector: opts.label_selector.clone(),
                 };
                 async move { grpc.list_sandbox_templates(request).await }
             })

crates/openshell-sdk/src/types.rs

@@ -159,6 +159,8 @@ pub struct SandboxTemplateListOptions {
     pub limit: u32,
     /// Offset into the result list.
     pub offset: u32,
+    /// Optional label selector in `key=value,key2=value2` form.
+    pub label_selector: String,
     /// List templates across all workspaces.
     pub all_workspaces: bool,
 }

crates/openshell-sdk/tests/client_mock.rs

@@ -968,6 +968,7 @@ async fn sandbox_template_crud_uses_default_workspace() {
         .list_sandbox_templates(SandboxTemplateListOptions {
             limit: 10,
             offset: 2,
+            label_selector: String::new(),
             all_workspaces: true,
         })
         .await

crates/openshell-server/src/grpc/sandbox.rs

@@ -781,11 +781,24 @@ pub(super) async fn handle_list_sandbox_templates(
     let limit = clamp_limit(request.limit, 100, MAX_PAGE_SIZE);
     let templates = if request.all_workspaces {
         require_platform_admin(&state.admin_role, &principal)?;
-        state
-            .store
-            .list_all_messages::<SandboxWorkloadTemplate>(limit, request.offset)
-            .await
-            .map_err(|e| Status::internal(format!("list sandbox templates failed: {e}")))?
+        if request.label_selector.is_empty() {
+            state
+                .store
+                .list_all_messages::<SandboxWorkloadTemplate>(limit, request.offset)
+                .await
+                .map_err(|e| Status::internal(format!("list sandbox templates failed: {e}")))?
+        } else {
+            crate::grpc::validation::validate_label_selector(&request.label_selector)?;
+            state
+                .store
+                .list_all_messages_with_selector::<SandboxWorkloadTemplate>(
+                    &request.label_selector,
+                    limit,
+                    request.offset,
+                )
+                .await
+                .map_err(|e| Status::internal(format!("list sandbox templates failed: {e}")))?
+        }
     } else {
         let authz = authorize_workspace(
             &state.store,
@@ -798,11 +811,27 @@ pub(super) async fn handle_list_sandbox_templates(
         let workspace = super::workspace::resolve_workspace(state.store.as_ref(), &authz.workspace)
             .await?
             .name;
-        state
-            .store
-            .list_messages::<SandboxWorkloadTemplate>(&workspace, limit, request.offset)
-            .await
-            .map_err(|e| Status::internal(format!("list sandbox templates failed: {e}")))?
+        if request.label_selector.is_empty() {
+            state
+                .store
+                .list_messages::<SandboxWorkloadTemplate>(&workspace, limit, request.offset)
+                .await
+                .map_err(|e| Status::internal(format!("list sandbox templates failed: {e}")))?
+        } else {
+            crate::grpc::validation::validate_label_selector(&request.label_selector)?;
+            state
+                .store
+                .list_messages_with_selector::<SandboxWorkloadTemplate>(
+                    &workspace,
+                    &request.label_selector,
+                    limit,
+                    request.offset,
+                )
+                .await
+                .map_err(|e| {
+                    Status::internal(format!("list sandbox templates with selector failed: {e}"))
+                })?
+        }
     };
     Ok(Response::new(ListSandboxTemplatesResponse { templates }))
 }
@@ -4222,6 +4251,7 @@ mod tests {
                 offset: 0,
                 workspace: "default".to_string(),
                 all_workspaces: false,
+                label_selector: String::new(),
             }),
         )
         .await
@@ -4255,6 +4285,61 @@ mod tests {
         assert_eq!(missing.code(), tonic::Code::NotFound);
     }
 
+    #[tokio::test]
+    async fn sandbox_template_list_filters_by_label_selector() {
+        let state = test_server_state().await;
+
+        let mut gpu = test_workload_template("gpu-kata");
+        gpu.metadata
+            .as_mut()
+            .expect("metadata")
+            .labels
+            .insert("team".to_string(), "runtime".to_string());
+        handle_create_sandbox_template(
+            &state,
+            authed_request(CreateSandboxTemplateRequest {
+                template: Some(gpu),
+                workspace: "default".to_string(),
+            }),
+        )
+        .await
+        .expect("gpu template create should succeed");
+
+        let mut cpu = test_workload_template("cpu-base");
+        cpu.metadata
+            .as_mut()
+            .expect("metadata")
+            .labels
+            .insert("team".to_string(), "batch".to_string());
+        handle_create_sandbox_template(
+            &state,
+            authed_request(CreateSandboxTemplateRequest {
+                template: Some(cpu),
+                workspace: "default".to_string(),
+            }),
+        )
+        .await
+        .expect("cpu template create should succeed");
+
+        let listed = handle_list_sandbox_templates(
+            &state,
+            authed_request(ListSandboxTemplatesRequest {
+                limit: 100,
+                offset: 0,
+                workspace: "default".to_string(),
+                all_workspaces: false,
+                label_selector: "team=runtime".to_string(),
+            }),
+        )
+        .await
+        .expect("template list with label selector should succeed")
+        .into_inner()
+        .templates;
+
+        assert_eq!(listed.len(), 1);
+        assert_eq!(listed[0].object_name(), "gpu-kata");
+    }
+
     #[tokio::test]
     async fn sandbox_template_create_rejects_whitespace_name() {
         let state = test_server_state().await;
@@ -4279,6 +4364,7 @@ mod tests {
                 offset: 0,
                 workspace: "default".to_string(),
                 all_workspaces: false,
+                label_selector: String::new(),
             }),
         )
         .await
@@ -4326,6 +4412,7 @@ mod tests {
                 offset: 0,
                 workspace: "beta".to_string(),
                 all_workspaces: false,
+                label_selector: String::new(),
             }),
         )
         .await

docs/sandboxes/manage-sandboxes.mdx

@@ -184,6 +184,7 @@ Inspect and manage templates:
 
 ```shell
 openshell sandbox template list
+openshell sandbox template list --label-selector team=runtime
 openshell sandbox template get gpu-kata
 openshell sandbox template delete gpu-kata
 ```