feat: allow nameless executables (#212)

jahvon · web-flow · commit 46062793bb58 · 2025-02-15T21:12:27.000-05:00
diff --git a/README.md b/README.md
@@ -5,7 +5,6 @@
 <p align="center">
     <a href="https://img.shields.io/github/v/release/jahvon/flow"><img src="https://img.shields.io/github/v/release/jahvon/flow" alt="GitHub release"></a>
     <a href="https://pkg.go.dev/github.com/jahvon/flow"><img src="https://pkg.go.dev/badge/github.com/jahvon/flow.svg" alt="Go Reference"></a>
-    <a href="https://goreportcard.com/report/github.com/jahvon/flow"><img src="https://goreportcard.com/badge/github.com/jahvon/flow" alt="Go Report Card"></a>
 </p>
 
 <p align="center">
diff --git a/cmd/internal/exec.go b/cmd/internal/exec.go
@@ -40,7 +40,7 @@ func RegisterExecCmd(ctx *context.Context, rootCmd *cobra.Command) {
 			io.TypesDocsURL("flowfile", "ExecutableRef"),
 			execExamples,
 		),
-		Args: cobra.MinimumNArgs(1),
+		Args: cobra.ArbitraryArgs,
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			execList, err := ctx.ExecutableCache.GetExecutableList(ctx.Logger)
 			if err != nil {
@@ -82,8 +82,14 @@ func execFunc(ctx *context.Context, cmd *cobra.Command, verb executable.Verb, ar
 		logger.FatalErr(err)
 	}
 
-	idArg := args[0]
-	ref := context.ExpandRef(ctx, executable.NewRef(idArg, verb))
+	var ref executable.Ref
+	if len(args) == 0 {
+		ref = context.ExpandRef(ctx, executable.NewRef("", verb))
+	} else {
+		idArg := args[0]
+		ref = context.ExpandRef(ctx, executable.NewRef(idArg, verb))
+	}
+
 	e, err := ctx.ExecutableCache.GetExecutableByRef(logger, ref)
 	if err != nil && errors.Is(cache.NewExecutableNotFoundError(ref.String()), err) {
 		logger.Debugf("Executable %s not found in cache, syncing cache", ref)
@@ -108,7 +114,10 @@ func execFunc(ctx *context.Context, cmd *cobra.Command, verb executable.Verb, ar
 		))
 	}
 
-	execArgs := args[1:]
+	execArgs := make([]string, 0)
+	if len(args) >= 2 {
+		execArgs = args[1:]
+	}
 	envMap, err := argUtils.ProcessArgs(e, execArgs, nil)
 	if err != nil {
 		logger.FatalErr(err)
@@ -369,6 +378,14 @@ Flag arguments are specified with the format 'flag=value' and positional argumen
 `
 	execExamples = `
 #### Examples
+**Execute a nameless flow in the current workspace with the 'install' verb**
+
+flow install
+
+**Execute a nameless flow in the 'ws' workspace with the 'test' verb**
+
+flow test ws
+
 **Execute the 'build' flow in the current workspace and namespace**
 
 flow exec build
diff --git a/cmd/internal/library.go b/cmd/internal/library.go
@@ -46,6 +46,8 @@ func libraryFunc(ctx *context.Context, cmd *cobra.Command, _ []string) {
 	wsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterWorkspaceFlag, false)
 	if wsFilter == "." {
 		wsFilter = ctx.Config.CurrentWorkspace
+	} else if wsFilter == executable.WildcardWorkspace {
+		wsFilter = ""
 	}
 
 	nsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterNamespaceFlag, false)
@@ -55,7 +57,7 @@ func libraryFunc(ctx *context.Context, cmd *cobra.Command, _ []string) {
 		logger.PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
 		fallthrough
 	case allNs:
-		nsFilter = "*"
+		nsFilter = executable.WildcardNamespace
 	case nsFilter == ".":
 		nsFilter = ctx.Config.CurrentNamespace
 	}
@@ -122,7 +124,7 @@ func glanceLibraryCmd(ctx *context.Context, cmd *cobra.Command, _ []string) {
 		logger.PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
 		fallthrough
 	case allNs:
-		nsFilter = "*"
+		nsFilter = executable.WildcardNamespace
 	case nsFilter == ".":
 		nsFilter = ctx.Config.CurrentNamespace
 	}
@@ -188,7 +190,7 @@ func viewLibraryFunc(ctx *context.Context, cmd *cobra.Command, args []string) {
 		logger.FatalErr(err)
 	}
 	id := args[1]
-	ws, ns, name := executable.ParseExecutableID(id)
+	ws, ns, name := executable.MustParseExecutableID(id)
 	if ws == "" {
 		ws = ctx.CurrentWorkspace.AssignedName()
 	}
diff --git a/development.flow b/development.flow
@@ -2,9 +2,7 @@
 visibility: private
 tags: [development]
 executables:
-  - verb: run
-    name: checks
-    aliases: [precommit, pc, ci, validate]
+  - verb: validate
     description: |
       Run the repository validation checks. This includes linting, tests, and code generation.
       Validate should be run before committing changes.
diff --git a/docs/cli/flow_exec.md b/docs/cli/flow_exec.md
@@ -16,6 +16,14 @@ See https://flowexec.io/#/types/flowfile#ExecutableVerb for more information on
 
 
 #### Examples
+**Execute a nameless flow in the current workspace with the 'install' verb**
+
+flow install
+
+**Execute a nameless flow in the 'ws' workspace with the 'test' verb**
+
+flow test ws
+
 **Execute the 'build' flow in the current workspace and namespace**
 
 flow exec build
diff --git a/docs/development.md b/docs/development.md
@@ -34,9 +34,9 @@ flow install deps
 flow build binary <output-path>
 
 # Validate code changes (runs tests, linters, codegen, etc)
-flow run checks
+flow validate
 
-# Run tests
+# Run only tests
 flow run tests
 ```
 
diff --git a/docs/guide/executable.md b/docs/guide/executable.md
@@ -56,6 +56,18 @@ the current workspace and namespace are assumed. See the [workspace guide](works
 
 The name of an executable can also be replaced with an alias if one is defined in the flowfile.
 
+**Nameless Executables**
+
+If an executable is defined without a namespace and name, it is considered "nameless" and can be run by its verb alone.
+Nameless executables cannot exist within a namespace.
+
+```shell
+# run the current workspaces nameless executable with the verb 'validate'
+flow validate
+# run the (non-current) 'my-project' workspaces nameless executable with the verb 'build'
+flow build my-project/
+```
+
 ## Flowfile
 
 The flowfile is the primary configuration file that defines what an executable should do. The file is written in YAML but
@@ -89,7 +101,7 @@ executables:
 
 ### Executables
 
-The only required field in an executable's configuration is the `name`.
+The only required field in an executable's configuration is the `name` (if the `namespace` is unset).
 
 Additionally, you can define the following fields:
 
diff --git a/docs/schemas/flowfile_schema.json b/docs/schemas/flowfile_schema.json
@@ -33,7 +33,6 @@
       "description": "The executable schema defines the structure of an executable in the Flow CLI.\nExecutables are the building blocks of workflows and are used to define the actions that can be performed in a workspace.\n",
       "type": "object",
       "required": [
-        "name",
         "verb"
       ],
       "properties": {
@@ -53,7 +52,7 @@
           "$ref": "#/definitions/ExecutableLaunchExecutableType"
         },
         "name": {
-          "description": "The name of the executable. \n\nName is used to reference the executable in the CLI using the format `workspace:namespace/name`.\n[Verb group + Name] must be unique within the namespace of the workspace.\n",
+          "description": "The name of the executable. \n\nName is used to reference the executable in the CLI using the format `workspace/namespace:name`.\n[Verb group + Name] must be unique within the namespace of the workspace. \nName is required if the executable is defined within a namespace.\n",
           "type": "string",
           "default": ""
         },
@@ -307,7 +306,7 @@
       }
     },
     "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\nThe workspace and namespace are optional.\nIf the workspace is not specified, the current workspace will be used.\nIf the namespace is not specified, the current namespace will be used.\n",
+      "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"
     },
     "ExecutableRenderExecutableType": {
diff --git a/docs/schemas/template_schema.json b/docs/schemas/template_schema.json
@@ -46,7 +46,7 @@
       }
     },
     "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\nThe workspace and namespace are optional.\nIf the workspace is not specified, the current workspace will be used.\nIf the namespace is not specified, the current namespace will be used.\n",
+      "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"
     },
     "Field": {
diff --git a/docs/types/flowfile.md b/docs/types/flowfile.md
@@ -84,7 +84,7 @@ Executables are the building blocks of workflows and are used to define the acti
 | `description` | A description of the executable. This description is rendered as markdown in the interactive UI.  | `string` |  |  |
 | `exec` |  | [ExecutableExecExecutableType](#ExecutableExecExecutableType) | <no value> |  |
 | `launch` |  | [ExecutableLaunchExecutableType](#ExecutableLaunchExecutableType) | <no value> |  |
-| `name` | The name of the executable.   Name is used to reference the executable in the CLI using the format `workspace:namespace/name`. [Verb group + Name] must be unique within the namespace of the workspace.  | `string` |  | ✘ |
+| `name` | The name of the executable.   Name is used to reference the executable in the CLI using the format `workspace/namespace:name`. [Verb group + Name] must be unique within the namespace of the workspace.  Name is required if the executable is defined within a namespace.  | `string` |  |  |
 | `parallel` |  | [ExecutableParallelExecutableType](#ExecutableParallelExecutableType) | <no value> |  |
 | `render` |  | [ExecutableRenderExecutableType](#ExecutableRenderExecutableType) | <no value> |  |
 | `request` |  | [ExecutableRequestExecutableType](#ExecutableRequestExecutableType) | <no value> |  |
@@ -254,9 +254,9 @@ A reference to an executable.
 The format is `<verb> <workspace>/<namespace>:<executable name>`.
 For example, `exec ws/ns:my-workflow`.
 
-The workspace and namespace are optional.
-If the workspace is not specified, the current workspace will be used.
-If the namespace is not specified, the current namespace will be used.
+- If the workspace is not specified, the current workspace will be used.
+- If the namespace is not specified, the current namespace will be used.
+- Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).
 
 
 **Type:** `string`
diff --git a/docs/types/template.md b/docs/types/template.md
@@ -49,9 +49,9 @@ A reference to an executable.
 The format is `<verb> <workspace>/<namespace>:<executable name>`.
 For example, `exec ws/ns:my-workflow`.
 
-The workspace and namespace are optional.
-If the workspace is not specified, the current workspace will be used.
-If the namespace is not specified, the current namespace will be used.
+- If the workspace is not specified, the current workspace will be used.
+- If the namespace is not specified, the current namespace will be used.
+- Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).
 
 
 **Type:** `string`
diff --git a/internal/context/context.go b/internal/context/context.go
@@ -115,7 +115,7 @@ func (ctx *Context) String() string {
 		ws = "unk"
 	}
 	if ns == "" {
-		ns = "*"
+		ns = executable.WildcardNamespace
 	}
 	return fmt.Sprintf("%s/%s", ws, ns)
 }
@@ -170,8 +170,8 @@ func (ctx *Context) Finalize() {
 
 func ExpandRef(ctx *Context, ref executable.Ref) executable.Ref {
 	id := ref.ID()
-	ws, ns, name := executable.ParseExecutableID(id)
-	if ws == "" {
+	ws, ns, name := executable.MustParseExecutableID(id)
+	if ws == "" || ws == executable.WildcardWorkspace {
 		ws = ctx.CurrentWorkspace.AssignedName()
 	}
 	if ns == "" {
diff --git a/internal/io/library/init.go b/internal/io/library/init.go
@@ -60,7 +60,7 @@ func (l *Library) setVisibleExecs() {
 			if label == withoutNamespaceLabel {
 				curNs = ""
 			} else if label == allNamespacesLabel {
-				curNs = "*"
+				curNs = executable.WildcardNamespace
 			} else {
 				curNs = label
 			}
@@ -89,8 +89,13 @@ func (l *Library) setVisibleWorkspaces() {
 
 	filter := l.filter
 	filteredWs := l.allWorkspaces
-	if filter.Workspace != "" {
-		for _, ws := range l.allWorkspaces {
+	switch {
+	case filter.Workspace == "":
+		// do nothing
+	case filter.Workspace == allWorkspacesLabel || filter.Workspace == executable.WildcardWorkspace:
+		// do nothing
+	default:
+		for _, ws := range filteredWs {
 			if ws.AssignedName() == filter.Workspace {
 				filteredWs = workspace.WorkspaceList{ws}
 				break
@@ -122,11 +127,11 @@ func (l *Library) setVisibleNamespaces() {
 	for _, ex := range l.allExecutables {
 		ns := ex.Ref().Namespace()
 		ws := ex.Ref().Workspace()
-		if filter.Namespace != "*" && filter.Namespace != "" && ns != filter.Namespace {
+		if filter.Namespace != executable.WildcardNamespace && filter.Namespace != "" && ns != filter.Namespace {
 			continue
 		} else if filterWs != allWorkspacesLabel && filterWs != "" && ws != filterWs {
 			continue
-		} else if ns == "" || ns == "*" {
+		} else if ns == "" || ns == executable.WildcardNamespace {
 			someWithoutNs = true
 			continue
 		}
diff --git a/internal/io/library/library.go b/internal/io/library/library.go
@@ -90,7 +90,7 @@ func ctxVal(ws, ns string) string {
 		ws = "unk"
 	}
 	if ns == "" {
-		ns = "*"
+		ns = executable.WildcardNamespace
 	}
 	return fmt.Sprintf("%s/%s", ws, ns)
 }
diff --git a/tests/exec_cmd_e2e_test.go b/tests/exec_cmd_e2e_test.go
@@ -31,5 +31,6 @@ var _ = Describe("exec e2e", func() {
 	},
 		Entry("print example", "examples:simple-print"),
 		Entry("tmp dir example", "examples:with-tmp-dir"),
+		Entry("nameless example", ""),
 	)
 })
diff --git a/tests/utils/context.go b/tests/utils/context.go
@@ -160,14 +160,23 @@ func initTestDirectories(t ginkgo.FullGinkgoTInterface) (string, string, string)
 		t.Fatalf("unable to create workspace directory: %v", err)
 	}
 
-	testData := builder.ExamplesExecFlowFile()
-	execDef, err := yaml.Marshal(testData)
+	examplesFile := builder.ExamplesExecFlowFile()
+	execDef, err := yaml.Marshal(examplesFile)
 	if err != nil {
 		t.Fatalf("unable to marshal test data: %v", err)
 	}
-	if err := os.WriteFile(filepath.Join(tmpWsDir, "testdata.flow"), execDef, 0600); err != nil {
+	if err := os.WriteFile(filepath.Join(tmpWsDir, "examples.flow"), execDef, 0600); err != nil {
 		t.Fatalf("unable to write test data: %v", err)
 	}
+	rootFile := builder.RootExecFlowFile()
+	rootDef, err := yaml.Marshal(rootFile)
+	if err != nil {
+		t.Fatalf("unable to marshal test data: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(tmpWsDir, "root.flow"), rootDef, 0600); err != nil {
+		t.Fatalf("unable to write test data: %v", err)
+	}
+
 	tmpConfigDir := filepath.Join(tmpDir, userConfigSubdir)
 	tmpCacheDir := filepath.Join(tmpDir, cacheSubdir)
 
diff --git a/tools/builder/exec.go b/tools/builder/exec.go
@@ -28,6 +28,21 @@ func SimpleExec(opts ...Option) *executable.Executable {
 	return e
 }
 
+func NamelessExec(opts ...Option) *executable.Executable {
+	e := &executable.Executable{
+		Verb:       "run",
+		Visibility: privateExecVisibility(),
+		Exec: &executable.ExecExecutableType{
+			Cmd: "echo 'hello from nameless'",
+		},
+	}
+	if len(opts) > 0 {
+		vals := NewOptionValues(opts...)
+		e.SetContext(vals.WorkspaceName, vals.WorkspacePath, vals.NamespaceName, vals.FlowFilePath)
+	}
+	return e
+}
+
 func ExecWithPauses(opts ...Option) *executable.Executable {
 	name := "with-pauses"
 	e := &executable.Executable{
diff --git a/tools/builder/flowfile.go b/tools/builder/flowfile.go
@@ -4,6 +4,21 @@ import (
 	"github.com/jahvon/flow/types/executable"
 )
 
+func RootExecFlowFile(opts ...Option) *executable.FlowFile {
+	d := &executable.FlowFile{
+		Visibility: privateFlowFileVisibility(),
+		Tags:       sharedExecTags(),
+		Executables: []*executable.Executable{
+			NamelessExec(opts...),
+		},
+	}
+	if len(opts) > 0 {
+		vals := NewOptionValues(opts...)
+		d.SetContext(vals.WorkspaceName, vals.WorkspacePath, vals.FlowFilePath)
+	}
+	return d
+}
+
 func ExamplesExecFlowFile(opts ...Option) *executable.FlowFile {
 	d := &executable.FlowFile{
 		Namespace:  "examples",
diff --git a/types/executable/executable.gen.go b/types/executable/executable.gen.go
diff --git a/types/executable/executable.go b/types/executable/executable.go
diff --git a/types/executable/executable_schema.yaml b/types/executable/executable_schema.yaml
diff --git a/types/executable/ref.go b/types/executable/ref.go

Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,7 @@`
`46`	`46`	`}`
`47`	`47`	`},`
`48`	`48`	`"ExecutableRef": {`
`49`		- "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\nThe workspace and namespace are optional.\nIf the workspace is not specified, the current workspace will be used.\nIf the namespace is not specified, the current namespace will be used.\n",
	`49`	+ "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",
`50`	`50`	`"type": "string"`
`51`	`51`	`},`
`52`	`52`	`"Field": {`