feat: add annotations on core types with --annotation filter on browse/workspace list

Author: jahvon

cmd/internal/browse.go

@@ -57,6 +57,7 @@ func RegisterBrowseCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	RegisterFlag(ctx, browseCmd, *flags.FilterNamespaceFlag)
 	RegisterFlag(ctx, browseCmd, *flags.FilterVerbFlag)
 	RegisterFlag(ctx, browseCmd, *flags.FilterTagFlag)
+	RegisterFlag(ctx, browseCmd, *flags.FilterAnnotationFlag)
 	RegisterFlag(ctx, browseCmd, *flags.FilterExecSubstringFlag)
 	RegisterFlag(ctx, browseCmd, *flags.AllNamespacesFlag)
 	RegisterFlag(ctx, browseCmd, *flags.VisibilityFlag)
@@ -105,6 +106,7 @@ func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
 
 	verbFilter := flags.ValueFor[string](cmd, *flags.FilterVerbFlag, false)
 	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
+	annotationFilter := flags.ValueFor[[]string](cmd, *flags.FilterAnnotationFlag, false)
 	subStr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
 	visStr := flags.ValueFor[string](cmd, *flags.VisibilityFlag, false)
@@ -129,12 +131,13 @@ func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	libraryModel := execIO.NewLibraryView(
 		ctx, allWs, allExecs,
 		execIO.Filter{
-			Workspace:  wsFilter,
-			Namespace:  nsFilter,
-			Verb:       executable.Verb(verbFilter),
-			Tags:       tagsFilter,
-			Substring:  subStr,
-			Visibility: visibilityFilter,
+			Workspace:   wsFilter,
+			Namespace:   nsFilter,
+			Verb:        executable.Verb(verbFilter),
+			Tags:        tagsFilter,
+			Annotations: annotationFilter,
+			Substring:   subStr,
+			Visibility:  visibilityFilter,
 		},
 		runFunc,
 	)
@@ -161,6 +164,7 @@ func listExecutables(ctx *context.Context, cmd *cobra.Command, _ []string) {
 
 	verbFilter := flags.ValueFor[string](cmd, *flags.FilterVerbFlag, false)
 	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
+	annotationFilter := flags.ValueFor[[]string](cmd, *flags.FilterAnnotationFlag, false)
 	outputFormat := flags.ValueFor[string](cmd, *flags.OutputFormatFlag, false)
 	substr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
@@ -183,6 +187,7 @@ func listExecutables(ctx *context.Context, cmd *cobra.Command, _ []string) {
 		FilterByNamespace(nsFilter).
 		FilterByVerb(executable.Verb(verbFilter)).
 		FilterByTags(tagsFilter).
+		FilterByAnnotations(annotationFilter).
 		FilterBySubstring(substr)
 
 	if TUIEnabled(ctx, cmd) {

cmd/internal/flags/types.go

@@ -87,6 +87,15 @@ var FilterTagFlag = &Metadata{
 	Required:  false,
 }
 
+var FilterAnnotationFlag = &Metadata{
+	Name: "annotation",
+	Usage: "Filter by annotations. Format: 'key=value' for exact value match, " +
+		"or 'key' for presence regardless of value. Repeat the flag for multiple selectors; " +
+		"all selectors must match (AND).",
+	Default:  []string{},
+	Required: false,
+}
+
 var OutputFormatFlag = &Metadata{
 	Name:      "output",
 	Shorthand: "o",

cmd/internal/template.go

@@ -123,7 +123,8 @@ func registerListTemplateCmd(ctx *context.Context, templateCmd *cobra.Command) {
 }
 
 func listTemplateFunc(ctx *context.Context, cmd *cobra.Command, _ []string) {
-	// TODO: include unregistered templates within the current ws
+	// TODO: include unregistered templates within the current ws;
+	// add --annotation filter flags (mirroring browse / workspace list)
 	tmpls, err := filesystem.LoadFlowFileTemplates(ctx.Config.Templates)
 	if err != nil {
 		logger.Log().FatalErr(err)

cmd/internal/workspace.go

@@ -363,12 +363,14 @@ func registerListWorkspaceCmd(ctx *context.Context, wsCmd *cobra.Command) {
 	}
 	RegisterFlag(ctx, listCmd, *flags.OutputFormatFlag)
 	RegisterFlag(ctx, listCmd, *flags.FilterTagFlag)
+	RegisterFlag(ctx, listCmd, *flags.FilterAnnotationFlag)
 	wsCmd.AddCommand(listCmd)
 }
 
 func listWorkspaceFunc(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	outputFormat := flags.ValueFor[string](cmd, *flags.OutputFormatFlag, false)
 	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
+	annotationFilter := flags.ValueFor[[]string](cmd, *flags.FilterAnnotationFlag, false)
 
 	workspaceCache, err := ctx.WorkspacesCache.GetLatestData()
 	if err != nil {
@@ -382,6 +384,9 @@ func listWorkspaceFunc(ctx *context.Context, cmd *cobra.Command, _ []string) {
 		if !common.Tags(ws.Tags).HasAnyTag(tagsFilter) {
 			continue
 		}
+		if !common.Annotations(ws.Annotations).MatchesAnnotationSelectors(annotationFilter) {
+			continue
+		}
 		filteredWorkspaces = append(filteredWorkspaces, ws)
 	}
 

docs/cli/flow_browse.md

@@ -19,16 +19,17 @@ flow browse [EXECUTABLE-REFERENCE] [flags]
 ### Options
 
 ```
-  -a, --all                 List from all namespaces.
-  -f, --filter string       Filter executable by reference substring.
-  -h, --help                help for browse
-  -l, --list                Show a simple list view of executables instead of interactive discovery.
-  -n, --namespace string    Filter executables by namespace.
-  -o, --output string       Output format. One of: yaml, json, or tui.
-  -t, --tag stringArray     Filter by tags.
-  -v, --verb string         Filter executables by verb.
-      --visibility string   Filter by visibility level (hierarchical). Valid: public, private, internal, hidden. Default: private
-  -w, --workspace string    Filter executables by workspace.
+  -a, --all                      List from all namespaces.
+      --annotation stringArray   Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND).
+  -f, --filter string            Filter executable by reference substring.
+  -h, --help                     help for browse
+  -l, --list                     Show a simple list view of executables instead of interactive discovery.
+  -n, --namespace string         Filter executables by namespace.
+  -o, --output string            Output format. One of: yaml, json, or tui.
+  -t, --tag stringArray          Filter by tags.
+  -v, --verb string              Filter executables by verb.
+      --visibility string        Filter by visibility level (hierarchical). Valid: public, private, internal, hidden. Default: private
+  -w, --workspace string         Filter executables by workspace.
 ```
 
 ### Options inherited from parent commands

docs/cli/flow_workspace_list.md

@@ -9,9 +9,10 @@ flow workspace list [flags]
 ### Options
 
 ```
-  -h, --help              help for list
-  -o, --output string     Output format. One of: yaml, json, or tui.
-  -t, --tag stringArray   Filter by tags.
+      --annotation stringArray   Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND).
+  -h, --help                     help for list
+  -o, --output string            Output format. One of: yaml, json, or tui.
+  -t, --tag stringArray          Filter by tags.
 ```
 
 ### Options inherited from parent commands

docs/public/schemas/flowfile_schema.json

@@ -12,6 +12,13 @@
         "type": "string"
       }
     },
+    "CommonAnnotations": {
+      "description": "A map of arbitrary string key/value metadata attached to the object.\nAnnotations are intended for use by external tools and integrations to\nstore system metadata. Unlike tags, annotations are not used for\nfiltering or display in the Flow UI - treat them as opaque state.\nKeys should be namespaced (e.g. `my-tool.example.com/state`) to avoid\ncollisions between tools.\n",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "CommonTags": {
       "description": "A list of tags.\nTags can be used with list commands to filter returned data.\n",
       "type": "array",
@@ -42,6 +49,10 @@
           "$ref": "#/definitions/CommonAliases",
           "default": []
         },
+        "annotations": {
+          "$ref": "#/definitions/CommonAnnotations",
+          "default": {}
+        },
         "description": {
           "description": "A description of the executable.\nThis description is rendered as markdown in the interactive UI.\n",
           "type": "string",
@@ -673,6 +684,10 @@
     "Verb": {}
   },
   "properties": {
+    "annotations": {
+      "$ref": "#/definitions/CommonAnnotations",
+      "default": {}
+    },
     "description": {
       "description": "A description of the executables defined within the flow file. This description will used as a shared description\nfor all executables in the flow file.\n",
       "type": "string",

docs/public/schemas/template_schema.json

@@ -46,6 +46,13 @@
         }
       }
     },
+    "CommonAnnotations": {
+      "description": "A map of arbitrary string key/value metadata attached to the object.\nAnnotations are intended for use by external tools and integrations to\nstore system metadata. Unlike tags, annotations are not used for\nfiltering or display in the Flow UI - treat them as opaque state.\nKeys should be namespaced (e.g. `my-tool.example.com/state`) to avoid\ncollisions between tools.\n",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "ExecutableRef": {
       "description": "A reference to an executable.\nThe format is `\u003cverb\u003e \u003cworkspace\u003e/\u003cnamespace\u003e:\u003cexecutable name\u003e`.\nFor example, `exec ws/ns:my-workflow`.\n\n- If the workspace is not specified, the current workspace will be used.\n- If the namespace is not specified, the current namespace will be used.\n- Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).\n",
       "type": "string"
@@ -135,6 +142,10 @@
     }
   },
   "properties": {
+    "annotations": {
+      "$ref": "#/definitions/CommonAnnotations",
+      "default": {}
+    },
     "artifacts": {
       "description": "A list of artifacts to be copied after generating the flow file.",
       "type": "array",

docs/public/schemas/workspace_schema.json

@@ -5,6 +5,13 @@
   "description": "Configuration for a workspace in the Flow CLI.\nThis configuration is used to define the settings for a workspace.\nEvery workspace has a workspace config file named `flow.yaml` in the root of the workspace directory.\n",
   "type": "object",
   "definitions": {
+    "CommonAnnotations": {
+      "description": "A map of arbitrary string key/value metadata attached to the object.\nAnnotations are intended for use by external tools and integrations to\nstore system metadata. Unlike tags, annotations are not used for\nfiltering or display in the Flow UI - treat them as opaque state.\nKeys should be namespaced (e.g. `my-tool.example.com/state`) to avoid\ncollisions between tools.\n",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
     "CommonTags": {
       "description": "A list of tags.\nTags can be used with list commands to filter returned data.\n",
       "type": "array",
@@ -45,6 +52,10 @@
     }
   },
   "properties": {
+    "annotations": {
+      "$ref": "#/definitions/CommonAnnotations",
+      "default": {}
+    },
     "description": {
       "description": "A description of the workspace. This description is rendered as markdown in the interactive UI.",
       "type": "string",

docs/types/flowfile.md

@@ -18,6 +18,7 @@ in order to be discovered by the CLI. It's configuration is used to define a gro
 
 | Field | Description | Type | Default | Required |
 | ----- | ----------- | ---- | ------- | :--------: |
+| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
 | `description` | A description of the executables defined within the flow file. This description will used as a shared description for all executables in the flow file.  | `string` |  |  |
 | `descriptionFile` | A path to a markdown file that contains the description of the executables defined within the flow file. | `string` |  |  |
 | `executables` |  | `array` ([Executable](#executable)) | [] |  |
@@ -39,6 +40,21 @@ Alternate names that can be used to reference the executable in the CLI.
 
 
 
+### CommonAnnotations
+
+A map of arbitrary string key/value metadata attached to the object.
+Annotations are intended for use by external tools and integrations to
+store system metadata. Unlike tags, annotations are not used for
+filtering or display in the Flow UI - treat them as opaque state.
+Keys should be namespaced (e.g. `my-tool.example.com/state`) to avoid
+collisions between tools.
+
+
+**Type:** `map` (`string` -> `string`)
+
+
+
+
 ### CommonTags
 
 A list of tags.
@@ -86,6 +102,7 @@ Executables are the building blocks of workflows and are used to define the acti
 | Field | Description | Type | Default | Required |
 | ----- | ----------- | ---- | ------- | :--------: |
 | `aliases` |  | [CommonAliases](#commonaliases) | [] |  |
+| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
 | `description` | A description of the executable. This description is rendered as markdown in the interactive UI.  | `string` |  |  |
 | `exec` |  | [ExecutableExecExecutableType](#executableexecexecutabletype) |  |  |
 | `launch` |  | [ExecutableLaunchExecutableType](#executablelaunchexecutabletype) |  |  |