feat: custom workspace verb alias mappings (#269)

Author: jahvon

desktop/src-tauri/src/types/generated/workspace.rs

@@ -122,6 +122,64 @@ impl ExecutableFilter {
         Default::default()
     }
 }
+#[doc = "A map of executable verbs to valid aliases. This allows you to use custom aliases for exec commands in the workspace.\nSetting this will override all of the default flow command aliases. The verbs and its mapped aliases must be valid flow verbs.\n\nIf set to an empty object, verb aliases will be disabled.\n"]
+#[doc = r""]
+#[doc = r" <details><summary>JSON schema</summary>"]
+#[doc = r""]
+#[doc = r" ```json"]
+#[doc = "{"]
+#[doc = "  \"description\": \"A map of executable verbs to valid aliases. This allows you to use custom aliases for exec commands in the workspace.\\nSetting this will override all of the default flow command aliases. The verbs and its mapped aliases must be valid flow verbs.\\n\\nIf set to an empty object, verb aliases will be disabled.\\n\","]
+#[doc = "  \"type\": \"object\","]
+#[doc = "  \"additionalProperties\": {"]
+#[doc = "    \"type\": \"array\","]
+#[doc = "    \"items\": {"]
+#[doc = "      \"type\": \"string\""]
+#[doc = "    }"]
+#[doc = "  }"]
+#[doc = "}"]
+#[doc = r" ```"]
+#[doc = r" </details>"]
+#[derive(:: serde :: Deserialize, :: serde :: Serialize, Clone, Debug)]
+#[serde(transparent)]
+pub struct VerbAliases(
+    pub ::std::collections::HashMap<::std::string::String, ::std::vec::Vec<::std::string::String>>,
+);
+impl ::std::ops::Deref for VerbAliases {
+    type Target =
+        ::std::collections::HashMap<::std::string::String, ::std::vec::Vec<::std::string::String>>;
+    fn deref(
+        &self,
+    ) -> &::std::collections::HashMap<::std::string::String, ::std::vec::Vec<::std::string::String>>
+    {
+        &self.0
+    }
+}
+impl ::std::convert::From<VerbAliases>
+    for ::std::collections::HashMap<::std::string::String, ::std::vec::Vec<::std::string::String>>
+{
+    fn from(value: VerbAliases) -> Self {
+        value.0
+    }
+}
+impl ::std::convert::From<&VerbAliases> for VerbAliases {
+    fn from(value: &VerbAliases) -> Self {
+        value.clone()
+    }
+}
+impl
+    ::std::convert::From<
+        ::std::collections::HashMap<::std::string::String, ::std::vec::Vec<::std::string::String>>,
+    > for VerbAliases
+{
+    fn from(
+        value: ::std::collections::HashMap<
+            ::std::string::String,
+            ::std::vec::Vec<::std::string::String>,
+        >,
+    ) -> Self {
+        Self(value)
+    }
+}
 #[doc = "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"]
 #[doc = r""]
 #[doc = r" <details><summary>JSON schema</summary>"]
@@ -154,6 +212,9 @@ impl ExecutableFilter {
 #[doc = "    \"tags\": {"]
 #[doc = "      \"default\": [],"]
 #[doc = "      \"$ref\": \"#/definitions/CommonTags\""]
+#[doc = "    },"]
+#[doc = "    \"verbAliases\": {"]
+#[doc = "      \"$ref\": \"#/definitions/VerbAliases\""]
 #[doc = "    }"]
 #[doc = "  }"]
 #[doc = "}"]
@@ -174,6 +235,12 @@ pub struct Workspace {
     pub executables: ::std::option::Option<ExecutableFilter>,
     #[serde(default = "defaults::workspace_tags")]
     pub tags: CommonTags,
+    #[serde(
+        rename = "verbAliases",
+        default,
+        skip_serializing_if = "::std::option::Option::is_none"
+    )]
+    pub verb_aliases: ::std::option::Option<VerbAliases>,
 }
 impl ::std::convert::From<&Workspace> for Workspace {
     fn from(value: &Workspace) -> Self {
@@ -188,6 +255,7 @@ impl ::std::default::Default for Workspace {
             display_name: Default::default(),
             executables: Default::default(),
             tags: defaults::workspace_tags(),
+            verb_aliases: Default::default(),
         }
     }
 }
@@ -264,6 +332,8 @@ pub mod builder {
             ::std::string::String,
         >,
         tags: ::std::result::Result<super::CommonTags, ::std::string::String>,
+        verb_aliases:
+            ::std::result::Result<::std::option::Option<super::VerbAliases>, ::std::string::String>,
     }
     impl ::std::default::Default for Workspace {
         fn default() -> Self {
@@ -273,6 +343,7 @@ pub mod builder {
                 display_name: Ok(Default::default()),
                 executables: Ok(Default::default()),
                 tags: Ok(super::defaults::workspace_tags()),
+                verb_aliases: Ok(Default::default()),
             }
         }
     }
@@ -330,6 +401,16 @@ pub mod builder {
                 .map_err(|e| format!("error converting supplied value for tags: {}", e));
             self
         }
+        pub fn verb_aliases<T>(mut self, value: T) -> Self
+        where
+            T: ::std::convert::TryInto<::std::option::Option<super::VerbAliases>>,
+            T::Error: ::std::fmt::Display,
+        {
+            self.verb_aliases = value
+                .try_into()
+                .map_err(|e| format!("error converting supplied value for verb_aliases: {}", e));
+            self
+        }
     }
     impl ::std::convert::TryFrom<Workspace> for super::Workspace {
         type Error = super::error::ConversionError;
@@ -342,6 +423,7 @@ pub mod builder {
                 display_name: value.display_name?,
                 executables: value.executables?,
                 tags: value.tags?,
+                verb_aliases: value.verb_aliases?,
             })
         }
     }
@@ -353,6 +435,7 @@ pub mod builder {
                 display_name: Ok(value.display_name),
                 executables: Ok(value.executables),
                 tags: Ok(value.tags),
+                verb_aliases: Ok(value.verb_aliases),
             }
         }
     }

desktop/src/types/generated/workspace.ts

@@ -31,6 +31,7 @@ export interface Workspace {
   displayName?: string;
   executables?: ExecutableFilter;
   tags?: CommonTags;
+  verbAliases?: VerbAliases;
   [k: string]: unknown;
 }
 export interface ExecutableFilter {
@@ -44,3 +45,13 @@ export interface ExecutableFilter {
   included?: string[];
   [k: string]: unknown;
 }
+/**
+ * A map of executable verbs to valid aliases. This allows you to use custom aliases for exec commands in the workspace.
+ * Setting this will override all of the default flow command aliases. The verbs and its mapped aliases must be valid flow verbs.
+ *
+ * If set to an empty object, verb aliases will be disabled.
+ *
+ */
+export interface VerbAliases {
+  [k: string]: string[];
+}

docs/guide/executable.md

@@ -41,6 +41,27 @@ For instance, `flow test my-app` is equivalent to `flow validate my-app`. This a
 interaction with the CLI, making it easier to remember and use. 
 *See the [verb reference](../types/flowfile.md#verb-groups) for a list all verbs and their synonyms.*
 
+**Custom Verb Aliases**
+
+You can customize which verb aliases are available in your workspace by configuring `verbAliases` in your [workspace configuration](workspace.md#workspace-configuration). This allows you to:
+
+- **Use custom aliases**: Define your own preferred aliases for verbs
+- **Disable default aliases**: Set an empty map `{}` to disable all verb aliases
+- **Selective aliases**: Only enable specific aliases for certain verbs
+
+```yaml
+# In your workspace flow.yaml
+verbAliases:
+  run: ["exec", "start"]    # `run` executables can be called with `exec` or `start` 
+  build: ["compile"]        # `build` executables can be called with `compile`
+  # No entry for `test` means no aliases for test executables
+
+# To disable all verb aliases:
+verbAliases: {}
+```
+
+With the above configuration, `flow start my-app` would run a `run` executable, but `flow execute my-app` would fail because `execute` is no longer a valid alias.
+
 > [!TIP]
 > Create shell aliases for commonly used verbs to make running executables easier. For example:
 > ```shell

docs/guide/workspace.md

@@ -18,6 +18,27 @@ When a workspace is created, a [configuration](#workspace-configuration) file is
 
 The workspace configuration file is a YAML file that contains the configuration options for the workspace. This file is located in the root directory of the workspace and is named `flow.yaml`.
 
+```yaml
+# Example workspace configuration
+displayName: "My Project"
+description: "A sample Flow workspace"
+descriptionFile: README.md
+tags: ["development", "web"]
+verbAliases:
+  run: ["exec", "start"]
+  build: ["compile"]
+executables:
+  included: ["scripts/", "tools/"]
+  excluded: ["node_modules/", ".git/"]
+```
+
+**Key Configuration Options:**
+
+- **verbAliases**: Customize which verb aliases are available when running executables. Set to `{}` to disable all aliases. See [custom verb aliases](executable.md#custom-verb-aliases) for more details.
+- **executables**: Configure which directories to include or exclude when discovering executables.
+- **displayName**,  **description**, and **descriptionFile**: Used in the interactive UI and library views.
+- **tags**: Used for filtering workspaces.
+
 For more details about workspace configuration options, see [Workspace](../types/workspace.md).
 
 

docs/schemas/workspace_schema.json

@@ -32,6 +32,16 @@
           }
         }
       }
+    },
+    "VerbAliases": {
+      "description": "A map of executable verbs to valid aliases. This allows you to use custom aliases for exec commands in the workspace.\nSetting this will override all of the default flow command aliases. The verbs and its mapped aliases must be valid flow verbs.\n\nIf set to an empty object, verb aliases will be disabled.\n",
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
     }
   },
   "properties": {
@@ -56,6 +66,9 @@
     "tags": {
       "$ref": "#/definitions/CommonTags",
       "default": []
+    },
+    "verbAliases": {
+      "$ref": "#/definitions/VerbAliases"
     }
   }
 }

docs/types/workspace.md

@@ -19,6 +19,7 @@ Every workspace has a workspace config file named `flow.yaml` in the root of the
 | `displayName` | The display name of the workspace. This is used in the interactive UI. | `string` |  |  |
 | `executables` |  | [ExecutableFilter](#ExecutableFilter) | <no value> |  |
 | `tags` |  | [CommonTags](#CommonTags) | [] |  |
+| `verbAliases` |  | [VerbAliases](#VerbAliases) | <no value> |  |
 
 
 ## Definitions
@@ -49,4 +50,17 @@ Tags can be used with list commands to filter returned data.
 | `excluded` | A list of directories to exclude from the executable search. | `array` (`string`) | [] |  |
 | `included` | A list of directories to include in the executable search. | `array` (`string`) | [] |  |
 
+### VerbAliases
+
+A map of executable verbs to valid aliases. This allows you to use custom aliases for exec commands in the workspace.
+Setting this will override all of the default flow command aliases. The verbs and its mapped aliases must be valid flow verbs.
+
+If set to an empty object, verb aliases will be disabled.
+
+
+**Type:** `map` (`string` -> `array` (`string`))
+
+
+
+
 

flow.yaml

@@ -4,6 +4,7 @@ description: |
    Source code for flow
    GitHub Repo: github.com/flowexec/flow
 descriptionFile: docs/development.md
+verbAliases: {}
 executables:
   excluded:
     - node_modules

internal/cache/executables_cache.go

@@ -10,6 +10,7 @@ import (
 	"github.com/flowexec/flow/internal/filesystem"
 	"github.com/flowexec/flow/types/common"
 	"github.com/flowexec/flow/types/executable"
+	"github.com/flowexec/flow/types/workspace"
 )
 
 const execCacheKey = "executables"
@@ -90,7 +91,7 @@ func (c *ExecutableCacheImpl) Update(logger io.Logger) error { //nolint:gocognit
 					continue
 				}
 				cacheData.ExecutableMap[e.Ref()] = flowFile.ConfigPath()
-				for _, ref := range enumerateExecutableAliasRefs(e) {
+				for _, ref := range enumerateExecutableAliasRefs(e, wsCfg.VerbAliases) {
 					cacheData.AliasMap[ref] = e.Ref()
 				}
 				cacheData.ConfigMap[flowFile.ConfigPath()] = WorkspaceInfo{
@@ -129,17 +130,23 @@ func (c *ExecutableCacheImpl) GetExecutableByRef(logger io.Logger, ref executabl
 		return exec, nil
 	}
 
+	var primaryRef executable.Ref
 	cfgPath, found := c.Data.ExecutableMap[ref]
+	//nolint:nestif
 	if !found {
-		if primaryRef, aliasFound := c.Data.AliasMap[ref]; aliasFound {
+		if aliasedPrimaryRef, aliasFound := c.Data.AliasMap[ref]; aliasFound {
+			primaryRef = aliasedPrimaryRef
 			cfgPath, found = c.Data.ExecutableMap[primaryRef]
 			if !found {
 				return nil, NewExecutableNotFoundError(ref.String())
 			}
 		} else {
 			return nil, NewExecutableNotFoundError(ref.String())
 		}
+	} else {
+		primaryRef = ref
 	}
+
 	cfg, err := filesystem.LoadFlowFile(cfgPath)
 	if err != nil {
 		return nil, errors.Wrap(err, "unable to load executable config")
@@ -164,7 +171,7 @@ func (c *ExecutableCacheImpl) GetExecutableByRef(logger io.Logger, ref executabl
 	cfg.Executables = append(cfg.Executables, generated...)
 
 	execs := cfg.Executables
-	exec, err := execs.FindByVerbAndID(ref.Verb(), ref.ID())
+	exec, err := execs.FindByVerbAndID(primaryRef.Verb(), primaryRef.ID())
 	if err != nil {
 		return nil, err
 	} else if exec == nil {
@@ -231,13 +238,39 @@ func (c *ExecutableCacheImpl) initExecutableCacheData(logger io.Logger) error {
 	return nil
 }
 
-func enumerateExecutableAliasRefs(exec *executable.Executable) executable.RefList {
+func enumerateExecutableAliasRefs(
+	exec *executable.Executable,
+	override *workspace.WorkspaceVerbAliases,
+) executable.RefList {
 	refs := make(executable.RefList, 0)
 
-	for _, verb := range executable.RelatedVerbs(exec.Verb) {
-		refs = append(refs, executable.NewRef(exec.ID(), verb))
-		for _, id := range exec.AliasesIDs() {
-			refs = append(refs, executable.NewRef(id, verb))
+	switch {
+	case override == nil:
+		// use default aliases
+		for _, verb := range executable.RelatedVerbs(exec.Verb) {
+			refs = append(refs, executable.NewRef(exec.ID(), verb))
+			for _, id := range exec.AliasesIDs() {
+				refs = append(refs, executable.NewRef(id, verb))
+			}
+		}
+	case len(*override) == 0:
+		// disable all aliases if override is set but empty
+		return refs
+	default:
+		// use overrides if provided
+		o := *override
+		if verbs, found := o[exec.Verb.String()]; found {
+			for _, v := range verbs {
+				vv := executable.Verb(v)
+				if err := vv.Validate(); err != nil {
+					// If the verb is not valid, skip it
+					continue
+				}
+				refs = append(refs, executable.NewRef(exec.ID(), vv))
+				for _, id := range exec.AliasesIDs() {
+					refs = append(refs, executable.NewRef(id, vv))
+				}
+			}
 		}
 	}