feat: add support for --with CLI flag for task inputs (#184)

## Description
Re-introduced the `--with` command line flag to allow passing task
inputs directly via the CLI. Updated the runner logic, tests, and
documentation to ensure proper handling and validation of inputs
provided through this flag. This enhances flexibility when defining and
running tasks.
...

## Related Issue

Fixes #17

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [X] New feature (non-breaking change which adds functionality)
- [ ] Other (security config, docs update, etc)

## Checklist before merging

- [X] Test, docs, adr added or updated as needed
- [X] [Contributor Guide
Steps](https://github.com/defenseunicorns/maru-runner/blob/main/CONTRIBUTING.md)
followed

---------

Co-authored-by: zamaz <[email protected]>
Co-authored-by: Wayne Starr <[email protected]>

Author: 3 people

README.md

@@ -217,6 +217,10 @@ Variables can be defined in several ways:
            setVariables:
              - name: FOO
          - cmd: echo ${FOO}
+         # Or drop the curly brackets
+         - cmd: echo $FOO
+         # Or use template syntax
+         - cmd: echo ${{ .variables.FOO }}
    ```
 
 1. As an environment variable prefixed with `MARU_`. In the example above, if you create an env var `MARU_FOO=bar`, then the`FOO` variable would be set to `bar`.
@@ -374,6 +378,8 @@ tasks:
     actions:
       # to use the input, reference it using INPUT_<INPUT_NAME> in all caps
       - cmd: echo $INPUT_HELLO_INPUT
+      # or use template syntax
+      - cmd: echo ${{ .inputs.hello-input }}
 
   - name: use-echo-var
     actions:
@@ -412,4 +418,15 @@ tasks:
           hello-input: hello unicorn
 ```
 
-Running `run len` will print the length of the inputs to `hello-input` and `another-input` to the console.
+Running `maru run len` will print the length of the inputs to `hello-input` and `another-input` to the console.
+
+#### Command Line Flags
+
+> [!NOTE]
+> The `--with` command line flag is experimental and likely to change as part of a comprehensive overhaul of the inputs/variables design.
+
+When creating a task with `inputs` you can also use the `--with` command line flag. Given the `length-of-inputs` task documented above, you can also run:
+
+```shell
+maru run length-of-inputs --with hello-input="hello unicorn"
+```

src/cmd/run.go

@@ -58,6 +58,9 @@ var dryRun bool
 // setRunnerVariables provides a map of set variables from the command line
 var setRunnerVariables map[string]string
 
+// withRunnerInputs provides a map of --with inputs from the command line
+var withRunnerInputs map[string]string
+
 var runCmd = &cobra.Command{
 	Use: "run",
 	PersistentPreRun: func(_ *cobra.Command, _ []string) {
@@ -136,7 +139,7 @@ var runCmd = &cobra.Command{
 		if len(args) > 0 {
 			taskName = args[0]
 		}
-		if err := runner.Run(tasksFile, taskName, setRunnerVariables, dryRun, auth); err != nil {
+		if err := runner.Run(tasksFile, taskName, setRunnerVariables, withRunnerInputs, dryRun, auth); err != nil {
 			message.Fatalf(err, "Failed to run action: %s", err.Error())
 		}
 	},
@@ -213,4 +216,6 @@ func init() {
 	runFlags.AddFlag(listAllPFlag)
 
 	runFlags.StringToStringVar(&setRunnerVariables, "set", nil, lang.CmdRunSetVarFlag)
+
+	runFlags.StringToStringVar(&withRunnerInputs, "with", nil, lang.CmdRunWithVarFlag)
 }

src/config/lang/english.go

@@ -49,7 +49,7 @@ const (
 	CmdRunShort       = "Runs a specified task from a task file"
 	CmdRunFlag        = "Name and location of task file to run"
 	CmdRunSetVarFlag  = "Set a runner variable from the command line (KEY=value)"
-	CmdRunWithVarFlag = "Set the inputs for a task from the command line (KEY=value)"
+	CmdRunWithVarFlag = "(experimental) Set the inputs for a task from the command line (KEY=value)"
 	CmdRunList        = "List available tasks in a task file"
 	CmdRunListAll     = "List all available tasks in a task file, including tasks from included files"
 	CmdRunDryRun      = "Validate the task without actually running any commands"

src/pkg/runner/runner.go

@@ -30,7 +30,7 @@ type Runner struct {
 }
 
 // Run runs a task from tasks file
-func Run(tasksFile types.TasksFile, taskName string, setVariables map[string]string, dryRun bool, auth map[string]string) error {
+func Run(tasksFile types.TasksFile, taskName string, setVariables map[string]string, withInputs map[string]string, dryRun bool, auth map[string]string) error {
 	if dryRun {
 		message.SLog.Info("Dry-run has been set - only printing the commands that would run:")
 	}
@@ -73,16 +73,16 @@ func Run(tasksFile types.TasksFile, taskName string, setVariables map[string]str
 		return err
 	}
 
-	// Check that this task is a valid task we can call (i.e. has defaults for any inputs since those cannot be set on the CLI)
-	if err := validateActionableTaskCall(task.Name, task.Inputs, nil); err != nil {
+	// Check that this task is a valid task we can call (i.e. has defaults for any unset inputs)
+	if err := validateActionableTaskCall(task.Name, task.Inputs, withInputs); err != nil {
 		return err
 	}
 
 	if err = runner.processTaskReferences(task, runner.tasksFile, setVariables); err != nil {
 		return err
 	}
 
-	err = runner.executeTask(task, nil)
+	err = runner.executeTask(task, withInputs)
 	return err
 }
 
@@ -278,13 +278,21 @@ func (r *Runner) executeTask(task types.Task, withs map[string]string) error {
 		r.currStackSize--
 	}()
 
-	defaultEnv := []string{}
+	env := []string{}
+	// Load the withs
+	for name, value := range withs {
+		env = append(env, utils.FormatEnvVar(name, value))
+	}
+	// load the default for each input if it has one and it isn't already set from withs
 	for name, inputParam := range task.Inputs {
+		if _, ok := withs[name]; ok {
+			continue
+		}
 		d := inputParam.Default
 		if d == "" {
 			continue
 		}
-		defaultEnv = append(defaultEnv, utils.FormatEnvVar(name, d))
+		env = append(env, utils.FormatEnvVar(name, d))
 	}
 
 	// load the tasks env file into the runner, can override previous task's env files
@@ -293,7 +301,7 @@ func (r *Runner) executeTask(task types.Task, withs map[string]string) error {
 	}
 
 	for _, action := range task.Actions {
-		action.Env = utils.MergeEnv(action.Env, defaultEnv)
+		action.Env = utils.MergeEnv(action.Env, env)
 		if err := r.performAction(action, withs, task.Inputs); err != nil {
 			return err
 		}

src/test/e2e/runner_inputs_test.go

@@ -152,4 +152,10 @@ func TestRunnerInputs(t *testing.T) {
 		require.NoError(t, err, stdOut, stdErr)
 		require.Contains(t, stdErr, "default-value")
 	})
+
+	t.Run("test that using the --with command line flag works", func(t *testing.T) {
+		stdOut, stdErr, err := e2e.Maru("run", "with:command-line-with", "--file", "src/test/tasks/inputs/tasks.yaml", "--with", "input1=input1", "--with", "input3=notthedefault", "--set", "FOO=baz")
+		require.NoError(t, err, stdOut, stdErr)
+		require.Contains(t, stdErr, "Input1Tmpl: input1 Input1Env: input1 Input2Tmpl: input2 Input2Env: input2 Input3Tmpl: notthedefault Input3Env: notthedefault Var: baz")
+	})
 }

src/test/tasks/inputs/tasks-with-inputs.yaml

@@ -59,3 +59,21 @@ tasks:
   - name: echo-bar
     actions:
       - cmd: echo $BAR
+
+  - name: command-line-with
+    description: Test task that uses the --with flag on the command line
+    inputs:
+      input1:
+        description: some input
+        required: true
+      input2:
+        description: some input
+        required: false
+        default: input2
+      input3:
+        description: some input
+        required: false
+        default: input3
+    actions:
+      - cmd: |
+          echo "Input1Tmpl: ${{ .inputs.input1 }} Input1Env: $INPUT_INPUT1 Input2Tmpl: ${{ .inputs.input2 }} Input2Env: ${INPUT_INPUT2} Input3Tmpl: ${{ .inputs.input3 }} Input3Env: $INPUT_INPUT3 Var: $FOO"

src/test/tasks/tasks.yaml

@@ -1,10 +1,11 @@
+# yaml-language-server: $schema=../../../tasks.schema.json
 includes:
   - foo: ./more-tasks/foo.yaml
   - intentional: ./loop-task.yaml
   - remote: https://raw.githubusercontent.com/defenseunicorns/maru-runner/${GIT_REVISION}/src/test/tasks/remote-import-tasks.yaml
   # This tests that Maru uses the correct Accept Header for the GitHub API when that is used
   - remote-api: https://api.github.com/repos/defenseunicorns/maru-runner/contents/src/test/tasks/tasks-no-default.yaml?ref=${GIT_REVISION}
-  # This tests that Maru properly handles authenitcation and GitLab paths (which are URL encoded)
+  # This tests that Maru properly handles authentication and GitLab paths (which are URL encoded)
   - remote-gitlab: https://gitlab.com/api/v4/projects/66014760/repository/files/tasks%2Eyaml/raw
 
 variables: