feat: Implement workflow step types with registry pattern (DEV-263, DEV-2969)

cmd/cmd_utils.go

@@ -31,6 +31,7 @@ import (
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/reexec"
+	stepPkg "github.com/cloudposse/atmos/pkg/runner/step"
 	"github.com/cloudposse/atmos/pkg/schema"
 	"github.com/cloudposse/atmos/pkg/ui"
 	u "github.com/cloudposse/atmos/pkg/utils"
@@ -249,7 +250,8 @@ func preCustomCommand(
 	if len(args) < requiredNoDefaultCount {
 		sb.WriteString(
 			fmt.Sprintf("Command requires at least %d argument(s) (no defaults provided for them):\n",
-				requiredNoDefaultCount))
+				requiredNoDefaultCount),
+		)
 
 		// List out which arguments are missing
 		missingIndex := 1
@@ -686,6 +688,9 @@ func executeCustomCommand(
 		log.Debug("Using working directory for custom command", "command", commandConfig.Name, "working_directory", workDir)
 	}
 
+	// Initialize step executor once before loop - reused across steps to preserve outputs.
+	executor := stepPkg.NewStepExecutor()
+
 	// Execute custom command's steps
 	for i, step := range commandConfig.Steps {
 		// Prepare template data for arguments
@@ -804,11 +809,48 @@ func executeCustomCommand(
 		commandToRun, err := e.ProcessTmpl(&atmosConfig, fmt.Sprintf("step-%d", i), step.Command, data, false)
 		errUtils.CheckErrorPrintAndExit(err, "", "")
 
-		// Execute the command step
-		commandName := fmt.Sprintf("%s-step-%d", commandConfig.Name, i)
+		// Determine step type - default to shell if not specified.
+		stepType := strings.TrimSpace(step.Type)
+		if stepType == "" {
+			stepType = "shell"
+		}
+
+		// Execute the step based on type.
+		switch stepType {
+		case "shell":
+			// Execute shell command (backward compatible).
+			commandName := fmt.Sprintf("%s-step-%d", commandConfig.Name, i)
+			err = e.ExecuteShell(commandToRun, commandName, workDir, env, false)
+		case "atmos":
+			// Execute atmos command.
+			args := strings.Fields(commandToRun)
+			err = e.ExecuteShellCommand(atmosConfig, "atmos", args, workDir, env, false, "")
+		default:
+			// Check if this is an extended step type (input, confirm, choose, etc.).
+			if stepPkg.IsExtendedStepType(stepType) {
+				// Convert Task to WorkflowStep for handler compatibility.
+				workflowStep := step.ToWorkflowStep()
+				// Update command with template-resolved value.
+				workflowStep.Command = commandToRun
+				// Propagate working directory to extended step if not already set.
+				if workflowStep.WorkingDirectory == "" {
+					workflowStep.WorkingDirectory = workDir
+				}
+
+				// Update environment variables for this step (reuse executor to preserve step outputs).
+				for _, envVar := range env {
+					parts := strings.SplitN(envVar, "=", 2)
+					if len(parts) == 2 {
+						executor.SetEnv(parts[0], parts[1])
+					}
+				}
 
-		// Pass the prepared environment with custom variables to the subprocess
-		err = e.ExecuteShell(commandToRun, commandName, workDir, env, false)
+				// Execute the extended step.
+				_, err = executor.Execute(context.Background(), &workflowStep)
+			} else {
+				err = fmt.Errorf("%w: unsupported step type %q for custom command step %d", errUtils.ErrInvalidWorkflowStepType, stepType, i)
+			}
+		}
 		errUtils.CheckErrorPrintAndExit(err, "", "")
 	}
 }
@@ -1128,7 +1170,8 @@ func resolveComponentPath(info *schema.ConfigAndStacksInfo, commandName string)
 		return handlePathResolutionError(err)
 	}
 
-	log.Debug("Resolved component from path",
+	log.Debug(
+		"Resolved component from path",
 		"original_path", info.ComponentFromArg,
 		"resolved_component", resolvedComponent,
 		"stack", info.Stack,
@@ -1272,7 +1315,8 @@ func StackFlagCompletion(cmd *cobra.Command, args []string, toComplete string) (
 				)
 				if err != nil {
 					// If resolution fails, fall through to list all stacks (graceful degradation)
-					log.Trace("Could not resolve path for stack completion, listing all stacks",
+					log.Trace(
+						"Could not resolve path for stack completion, listing all stacks",
 						"path", component,
 						"error", err,
 					)
@@ -1283,7 +1327,8 @@ func StackFlagCompletion(cmd *cobra.Command, args []string, toComplete string) (
 					return output, cobra.ShellCompDirectiveNoFileComp
 				}
 				component = resolvedComponent
-				log.Trace("Resolved path for stack completion",
+				log.Trace(
+					"Resolved path for stack completion",
 					"original", args[0],
 					"resolved", component,
 				)

docs/prd/command-registry-pattern.md

@@ -623,6 +623,8 @@ func Execute() error {
 
 ### Custom Command Override Behavior
 
+> **Shipped behavior (corrected).** An earlier draft of this section claimed a same-named custom command "reuses the built-in and **replaces its behavior**." That is **not** what ships. Since **PR #2191** ("allow custom commands to merge into built-in namespaces at any level"), a custom command whose name collides with a built-in may **add subcommands** under that built-in's namespace, but it **cannot replace the built-in's behavior with steps** — the built-in is preserved and the steps are ignored with a warning. Replacing a built-in's behavior is an opt-in capability specified in [Overriding Built-in Commands with Step-Based Custom Commands](./custom-command-builtin-override.md) (via `override: true` plus an `invoke: built-in` step), not the default. The scenarios below are reframed to match reality.
+
 **Scenario 1: Custom command with same name as built-in (top-level command)**
 
 ```yaml
@@ -636,7 +638,7 @@ commands:
       - terraform {{ .arguments.subcommand }}
 ```
 
-**Result:** Custom `terraform` command **reuses** the built-in `terraform` command and **replaces its behavior**.
+**Result (default):** The built-in `terraform` command is **preserved** and the custom `steps` are **ignored** with the warning *"Custom command … defines steps that conflict with built-in command …; built-in behavior preserved, custom steps ignored"* (`cmd/cmd_utils.go`). To actually replace the built-in's behavior — and still reach the native `terraform` from a step — opt in with `override: true` and an `invoke: built-in` step, per the [override PRD](./custom-command-builtin-override.md).
 
 **Scenario 2: Custom command extending built-in with subcommands**
 
@@ -706,12 +708,15 @@ func processCustomCommands(
 }
 ```
 
-**Key behaviors:**
-- **Top-level custom command with existing name** → reuses registry command, can replace behavior or add subcommands
+> **Note:** the snippet above is the original illustrative sketch and predates **PR #2191**. The current `processCustomCommands` (`cmd/cmd_utils.go`) uses `findSubcommand` at every level and, on a name collision, **reuses the existing built-in and ignores any custom `steps`** (warning emitted). It does not replace the built-in's behavior. See the corrected key behaviors below.
+
+**Key behaviors (shipped):**
+- **Top-level custom command with existing built-in name** → reuses the built-in; may add subcommands under it; custom `steps` are **ignored** (warning). Replacing behavior requires opt-in `override: true` — see the [override PRD](./custom-command-builtin-override.md).
 - **Top-level custom command with new name** → creates new command
-- **Nested custom commands** → always added as subcommands to parent
+- **Nested custom commands, new name** → added as a new subcommand under the parent
+- **Nested custom commands, name collision** → `findSubcommand` runs at every level, so a nested name that collides with an existing subcommand (built-in or one already added) **reuses the existing command**; if the colliding custom command declares `steps`, they are **ignored** (warning emitted). This is the same collision behavior as top-level commands — it is not limited to the top level.
 
-**No changes needed to custom command processing** - the registry pattern coexists perfectly.
+The registry pattern itself needs no changes for this; the override capability is layered on top via the [override PRD](./custom-command-builtin-override.md).
 
 ## Migration Guide
 
@@ -1817,19 +1822,21 @@ func RegisterPlugin(plugin *Plugin) {
 
 ### Q: Can custom commands still override built-in commands?
 
-**A:** Yes. The execution order is:
+**A:** Not by default. The execution order is:
 1. Built-in commands registered via registry
 2. Custom commands processed from atmos.yaml
-3. If custom command has same name → overrides built-in
-4. If custom command has new name → extends available commands
+3. If a custom command has the **same name** as a built-in → it may **add subcommands** under that namespace, but its `steps` are **ignored** and the built-in's behavior is preserved (warning emitted) — see PR #2191.
+4. If a custom command has a **new name** → extends available commands
+
+Replacing a built-in command's behavior with steps is an **opt-in** capability (`override: true`), and a step can call the native built-in via `invoke: built-in`. See [Overriding Built-in Commands with Step-Based Custom Commands](./custom-command-builtin-override.md).
 
 ### Q: Do I need to update my atmos.yaml?
 
 **A:** No. The registry pattern is purely internal. User-facing configuration and behavior remain unchanged.
 
 ### Q: What happens if I have a custom command named "about"?
 
-**A:** Your custom command will override the built-in `about` command, just like it does today. The registry pattern doesn't change this behavior.
+**A:** By default the built-in `about` command is preserved; a same-named custom command's `steps` are ignored (warning emitted), though you may add subcommands under it. To replace the built-in's behavior, opt in with `override: true` (see the [override PRD](./custom-command-builtin-override.md)). The registry pattern itself doesn't change this.
 
 ### Q: Can multiple commands register with the same name?