feat: visibility flag for browse cmd (#323)

Add support for filtering executables by visibility. This will allow the
inclusion of internal and hidden executables in the output when the flag
is set to those values. The returned executables use a hierarchical
match instead of exact (i.e. internal will also return private and
public)

Author: jahvon

cmd/internal/browse.go

@@ -13,6 +13,7 @@ import (
 	execIO "github.com/flowexec/flow/internal/io/executable"
 	"github.com/flowexec/flow/internal/io/library"
 	"github.com/flowexec/flow/internal/logger"
+	"github.com/flowexec/flow/types/common"
 	"github.com/flowexec/flow/types/executable"
 )
 
@@ -59,6 +60,7 @@ func RegisterBrowseCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	RegisterFlag(ctx, browseCmd, *flags.FilterTagFlag)
 	RegisterFlag(ctx, browseCmd, *flags.FilterExecSubstringFlag)
 	RegisterFlag(ctx, browseCmd, *flags.AllNamespacesFlag)
+	RegisterFlag(ctx, browseCmd, *flags.VisibilityFlag)
 	rootCmd.AddCommand(browseCmd)
 }
 
@@ -106,6 +108,15 @@ func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
 	subStr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
+	visStr := flags.ValueFor[string](cmd, *flags.VisibilityFlag, false)
+	visibilityFilter := common.VisibilityPrivate
+	if visStr != "" {
+		visibilityFilter = common.Visibility(visStr)
+		if !isValidVisibility(visibilityFilter) {
+			logger.Log().Fatalf("invalid visibility: %s (valid: public, private, internal, hidden)", visStr)
+		}
+	}
+
 	allExecs, err := ctx.ExecutableCache.GetExecutableList()
 	if err != nil {
 		logger.Log().FatalErr(err)
@@ -119,11 +130,12 @@ func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	libraryModel := library.NewLibraryView(
 		ctx, allWs, allExecs,
 		library.Filter{
-			Workspace: wsFilter,
-			Namespace: nsFilter,
-			Verb:      executable.Verb(verbFilter),
-			Tags:      tagsFilter,
-			Substring: subStr,
+			Workspace:  wsFilter,
+			Namespace:  nsFilter,
+			Verb:       executable.Verb(verbFilter),
+			Tags:       tagsFilter,
+			Substring:  subStr,
+			Visibility: visibilityFilter,
 		},
 		io.Theme(ctx.Config.Theme.String()),
 		runFunc,
@@ -154,13 +166,22 @@ func listExecutables(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	outputFormat := flags.ValueFor[string](cmd, *flags.OutputFormatFlag, false)
 	substr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
+	visStr := flags.ValueFor[string](cmd, *flags.VisibilityFlag, false)
+	visibilityFilter := common.VisibilityPrivate
+	if visStr != "" {
+		visibilityFilter = common.Visibility(visStr)
+		if !isValidVisibility(visibilityFilter) {
+			logger.Log().Fatalf("invalid visibility: %s (valid: public, private, internal, hidden)", visStr)
+		}
+	}
+
 	allExecs, err := ctx.ExecutableCache.GetExecutableList()
 	if err != nil {
 		logger.Log().FatalErr(err)
 	}
 	filteredExec := allExecs
 	filteredExec = filteredExec.
-		FilterByWorkspace(wsFilter).
+		FilterByWorkspaceWithVisibility(wsFilter, visibilityFilter).
 		FilterByNamespace(nsFilter).
 		FilterByVerb(executable.Verb(verbFilter)).
 		FilterByTags(tagsFilter).
@@ -219,3 +240,12 @@ func viewExecutable(ctx *context.Context, cmd *cobra.Command, args []string) {
 		execIO.PrintExecutable(outputFormat, exec)
 	}
 }
+
+func isValidVisibility(v common.Visibility) bool {
+	switch v {
+	case common.VisibilityPublic, common.VisibilityPrivate, common.VisibilityInternal, common.VisibilityHidden:
+		return true
+	default:
+		return false
+	}
+}

cmd/internal/flags/types.go

@@ -72,6 +72,13 @@ var FilterVerbFlag = &Metadata{
 	Required:  false,
 }
 
+var VisibilityFlag = &Metadata{
+	Name:     "visibility",
+	Usage:    "Filter by visibility level (hierarchical). Valid: public, private, internal, hidden. Default: private",
+	Default:  "",
+	Required: false,
+}
+
 var FilterTagFlag = &Metadata{
 	Name:      "tag",
 	Shorthand: "t",

docs/cli/flow_browse.md

@@ -19,15 +19,16 @@ 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. (default "tui")
-  -t, --tag stringArray    Filter by tags.
-  -v, --verb string        Filter executables by verb.
-  -w, --workspace string   Filter executables by workspace.
+  -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. (default "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

internal/io/library/init.go

@@ -75,7 +75,7 @@ func (l *Library) setVisibleExecs() {
 	filter := l.filter
 	filteredExec := l.allExecutables
 	filteredExec = filteredExec.
-		FilterByWorkspace(curWs).
+		FilterByWorkspaceWithVisibility(curWs, filter.Visibility).
 		FilterByNamespace(curNs).
 		FilterByVerb(filter.Verb).
 		FilterByTags(filter.Tags).

internal/io/library/library.go

@@ -48,6 +48,7 @@ type Filter struct {
 	Verb                 executable.Verb
 	Tags                 common.Tags
 	Substring            string
+	Visibility           common.Visibility
 }
 
 func NewLibrary(

types/common/common.go

@@ -73,3 +73,22 @@ func (v Visibility) IsInternal() bool {
 func (v Visibility) IsHidden() bool {
 	return v == VisibilityHidden
 }
+
+// Level returns the hierarchical level of the visibility for filtering comparisons.
+// Hierarchy (most to least visible):
+// 1: public, 2: private, 3: internal, 4: hidden
+// Defaults to private when unknown.
+func (v Visibility) Level() int {
+	switch v {
+	case VisibilityPublic:
+		return 1
+	case VisibilityPrivate:
+		return 2
+	case VisibilityInternal:
+		return 3
+	case VisibilityHidden:
+		return 4
+	default:
+		return 2
+	}
+}

types/executable/executable.go

@@ -288,19 +288,25 @@ func (e *Executable) MergeTags(tags common.Tags) {
 	e.Tags = slices.Compact(append(e.Tags, tags...))
 }
 
-// IsVisibleFromWorkspace returns true if the executable should be shown in terminal output for the given workspace.
-func (e *Executable) IsVisibleFromWorkspace(workspaceFilter string) bool {
-	matchesWsFiler := e.Workspace() == workspaceFilter || workspaceFilter == "" || workspaceFilter == WildcardWorkspace
-	if e.Visibility == nil {
-		return matchesWsFiler
+// IsVisibleFromWorkspace returns true if the executable should be shown in the UI for the given workspace
+// and visibility filter.
+func (e *Executable) IsVisibleFromWorkspace(workspaceFilter string, visibilityFilter common.Visibility) bool {
+	matchesWs := e.Workspace() == workspaceFilter || workspaceFilter == "" || workspaceFilter == WildcardWorkspace
+
+	execVis := common.VisibilityPrivate
+	if e.Visibility != nil {
+		execVis = common.Visibility(*e.Visibility)
 	}
-	switch common.Visibility(*e.Visibility) {
-	case common.VisibilityPrivate:
-		return matchesWsFiler
+
+	switch execVis {
 	case common.VisibilityPublic:
-		return true
-	case common.VisibilityInternal, common.VisibilityHidden:
-		return false
+		return visibilityFilter.Level() >= common.VisibilityPublic.Level()
+	case common.VisibilityPrivate:
+		return matchesWs && visibilityFilter.Level() >= common.VisibilityPrivate.Level()
+	case common.VisibilityInternal:
+		return matchesWs && visibilityFilter.Level() >= common.VisibilityInternal.Level()
+	case common.VisibilityHidden:
+		return matchesWs && visibilityFilter.Level() >= common.VisibilityHidden.Level()
 	default:
 		return false
 	}
@@ -444,9 +450,13 @@ func (l ExecutableList) FilterBySubstring(str string) ExecutableList {
 }
 
 func (l ExecutableList) FilterByWorkspace(ws string) ExecutableList {
+	return l.FilterByWorkspaceWithVisibility(ws, common.VisibilityPrivate)
+}
+
+func (l ExecutableList) FilterByWorkspaceWithVisibility(ws string, vis common.Visibility) ExecutableList {
 	executables := make(ExecutableList, 0)
 	for _, exec := range l {
-		if exec.IsVisibleFromWorkspace(ws) {
+		if exec.IsVisibleFromWorkspace(ws, vis) {
 			executables = append(executables, exec)
 		}
 	}

types/executable/executables_test.go

@@ -122,9 +122,9 @@ var _ = Describe("Executable", func() {
 		v := executable.ExecutableVisibility(*visibility)
 		exec.Visibility = &v
 		if wsMatch {
-			Expect(exec.IsVisibleFromWorkspace(testWsName)).To(Equal(expected))
+			Expect(exec.IsVisibleFromWorkspace(testWsName, common.VisibilityPrivate)).To(Equal(expected))
 		} else {
-			Expect(exec.IsVisibleFromWorkspace("another-ws")).To(Equal(expected))
+			Expect(exec.IsVisibleFromWorkspace("another-ws", common.VisibilityPrivate)).To(Equal(expected))
 		}
 	},
 		Entry("public from ws", common.VisibilityPublic.NewPointer(), true, true),
@@ -330,3 +330,58 @@ var _ = DescribeTable("HasFlowFileTemplateExt", func(file string, expected bool)
 	Entry("ends with .flow.tmpl + something else", "development.flow.tmpl.txt", false),
 	Entry("ends with something else", "development.flow.txt", false),
 )
+
+var _ = Describe("Executable Visibility", func() {
+	It("should show public executables with any filter", func() {
+		ws := "ws1"
+		vis := common.VisibilityPublic
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace("ws2", common.VisibilityPublic)).To(BeTrue())
+		Expect(ex.IsVisibleFromWorkspace("ws2", common.VisibilityPrivate)).To(BeTrue())
+		Expect(ex.IsVisibleFromWorkspace("ws2", common.VisibilityInternal)).To(BeTrue())
+	})
+
+	It("should respect workspace scoping for private", func() {
+		ws := "ws1"
+		vis := common.VisibilityPrivate
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityPrivate)).To(BeTrue())
+		Expect(ex.IsVisibleFromWorkspace("ws2", common.VisibilityPrivate)).To(BeFalse())
+	})
+
+	It("should hide private with public filter", func() {
+		ws := "ws1"
+		vis := common.VisibilityPrivate
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityPublic)).To(BeFalse())
+	})
+
+	It("should hide internal without internal+ filter", func() {
+		ws := "ws1"
+		vis := common.VisibilityInternal
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityPrivate)).To(BeFalse())
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityInternal)).To(BeTrue())
+	})
+
+	It("should respect workspace scoping for internal", func() {
+		ws := "ws1"
+		vis := common.VisibilityInternal
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace("ws2", common.VisibilityInternal)).To(BeFalse())
+	})
+
+	It("should only show hidden with hidden filter", func() {
+		ws := "ws1"
+		vis := common.VisibilityHidden
+		ex := &executable.Executable{Visibility: (*executable.ExecutableVisibility)(&vis)}
+		ex.SetContext(ws, "path", "", "file.flow")
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityInternal)).To(BeFalse())
+		Expect(ex.IsVisibleFromWorkspace(ws, common.VisibilityHidden)).To(BeTrue())
+	})
+})