cloudposse
diff --git a/‎.claude/skills/docs/SKILL.md‎
Lines changed: 11 additions & 0 deletions b/‎.claude/skills/docs/SKILL.md‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 53 additions & 1 deletion b/‎.github/workflows/test.yml‎
Lines changed: 53 additions & 1 deletion
diff --git a/‎cmd/cmd_utils.go‎
Lines changed: 39 additions & 2 deletions b/‎cmd/cmd_utils.go‎
Lines changed: 39 additions & 2 deletions
diff --git a/‎cmd/cmd_utils_test.go‎
Lines changed: 16 additions & 0 deletions b/‎cmd/cmd_utils_test.go‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎docs/prd/compose-components.md‎
Lines changed: 186 additions & 0 deletions b/‎docs/prd/compose-components.md‎
Lines changed: 186 additions & 0 deletions
@@ -37,6 +37,17 @@ Every new or changed `atmos.yaml` section needs configuration docs.
 - Use `<dl>`, `<dt>`, and `<dd>` for configuration keys and option definitions.
 - Include defaults, supported values, and environment variables when they are part of the public interface.
 
+## Sidebar Hierarchy
+
+For configuration docs, make the sidebar resemble the YAML hierarchy.
+
+- Parent categories may link to the page for the object they represent.
+- Prefer visible labels that are config keys or object names, such as `workflows`, `workflow`, `steps`, and `env`.
+- Avoid editorial labels like "Overview", "Execution", or "Runtime Context" when the page represents a configuration object.
+- Do not promote enum values or type-specific parameters to sidebar peers unless they are independent configuration objects.
+- When possible, use folder structure plus `_category_.json` so autogenerated sidebar entries inherit the YAML-shaped hierarchy from the docs tree.
+- If site-level sidebar sorting prevents YAML-order rendering, use explicit sidebar entries for that section rather than changing global sidebar behavior.
+
 ## Command Docs
 
 When command behavior is configured by `atmos.yaml`, link command docs back to configuration docs.
 
@@ -765,8 +765,60 @@ jobs:
               ]
             }
 
+  # run container step tests against a local registry (build -> push -> run)
+  # Docker is available directly on the runner (see the k3s job), and a
+  # registry:2 service container provides a hermetic push/pull target on
+  # localhost:5000 so the full build -> push -> run cycle is exercised without
+  # GitHub Container Registry, leftover packages, or fork-PR token limits.
+  container-step:
+    name: "[container-step] example"
+    needs: build
+    runs-on: ubuntu-latest
+
+    services:
+      registry:
+        image: registry:2
+        ports:
+          - 5000:5000
+
+    timeout-minutes: 15
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: build-artifacts-linux
+          path: /usr/local/bin
+
+      - name: Set execute permissions on atmos
+        run: chmod +x /usr/local/bin/atmos
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run container steps (run, build, bake, push, workspace, env)
+        working-directory: examples/container-step
+        run: |
+          set -euo pipefail
+          atmos workflow hello -f container-step
+          atmos workflow build-run -f container-step
+          atmos workflow bake-build-run -f container-step
+          atmos workflow push-local-registry -f container-step
+          atmos workflow workspace -f container-step
+          atmos workflow env -f container-step
+
+      - name: Verify a failing container step propagates a non-zero exit code
+        working-directory: examples/container-step
+        run: |
+          if atmos workflow failing-check -f container-step; then
+            echo "expected the 'failing-check' workflow to fail, but it succeeded"
+            exit 1
+          fi
+          echo "failing-check correctly returned a non-zero exit code"
+
   release:
-    needs: [test, lint, mock, k3s, floci, floci-go, docker, validate]
+    needs: [test, lint, mock, k3s, floci, floci-go, docker, validate, container-step]
     if: github.event_name == 'push'
     uses: cloudposse/.github/.github/workflows/shared-go-auto-release.yml@8244c7c9142e92281e7841f655fa48e9ceb9b454 # main
     with:
 
@@ -724,7 +724,7 @@ func executeCustomCommand(
 	// Determine working directory for command execution.
 	workDir, err := resolveWorkingDirectory(commandConfig.WorkingDirectory, atmosConfig.BasePath, currentDirPath)
 	if err != nil {
-		errUtils.CheckErrorPrintAndExit(err, "Invalid working_directory", "https://atmos.tools/cli/configuration/commands#working-directory")
+		errUtils.CheckErrorPrintAndExit(err, "Invalid working_directory", "https://atmos.tools/cli/configuration/commands/working-directory")
 	}
 	if commandConfig.WorkingDirectory != "" {
 		log.Debug("Using working directory for custom command", "command", commandConfig.Name, "working_directory", workDir)
@@ -734,7 +734,7 @@ func executeCustomCommand(
 	// the Atmos process, so it must be the final step and must not set
 	// supervisor-only fields (tty, interactive, retry, timeout, output).
 	if err := schema.ValidateExecTasks(commandConfig.Steps); err != nil {
-		errUtils.CheckErrorPrintAndExit(err, "", "https://atmos.tools/cli/configuration/commands#interactive-and-tty-steps")
+		errUtils.CheckErrorPrintAndExit(err, "", "https://atmos.tools/cli/configuration/commands/steps#interactive-and-tty-steps")
 	}
 
 	// Initialize step executor once before loop - reused across steps to preserve outputs.
@@ -897,6 +897,14 @@ func executeCustomCommand(
 		}
 
 		// Execute the step based on type.
+		//
+		// shell/exec/atmos use the legacy, cross-platform, child-reaping paths
+		// below; only genuinely-extended step types (container, input, confirm,
+		// …) route through the registered step handlers via the default case.
+		// Routing shell/atmos through the handlers regressed Windows (handlers
+		// hardcode `sh -c` → exit 126) and leaked orphaned `atmos` child
+		// processes on Linux (no process-group cleanup), so they stay on the
+		// legacy paths.
 		switch stepType {
 		case "shell":
 			// Execute shell command (backward compatible).
@@ -937,6 +945,20 @@ func executeCustomCommand(
 				workflowStep := step.ToWorkflowStep()
 				// Update command with template-resolved value.
 				workflowStep.Command = commandToRun
+				// Carry env onto the step so handlers that read step.Env (e.g. the
+				// container handler's in-container env) see it. The step's own
+				// declared `env:` had its map keys lowercased by Viper, so restore
+				// the original case from the shared env case map, then merge it over
+				// the resolved command/process env (step vars win on collisions).
+				stepOwnEnv := workflowStep.Env
+				if atmosConfig.CaseMaps != nil {
+					stepOwnEnv = atmosConfig.CaseMaps.ApplyCase("env", stepOwnEnv)
+				}
+				mergedStepEnv := envSliceToMap(env)
+				for key, value := range stepOwnEnv {
+					mergedStepEnv[key] = value
+				}
+				workflowStep.Env = mergedStepEnv
 				// Propagate working directory to extended step if not already set.
 				if workflowStep.WorkingDirectory == "" {
 					workflowStep.WorkingDirectory = workDir
@@ -975,6 +997,21 @@ func cloneCommand(orig *schema.Command) (*schema.Command, error) {
 	return &clone, nil
 }
 
+func envSliceToMap(env []string) map[string]string {
+	if len(env) == 0 {
+		return nil
+	}
+	result := make(map[string]string, len(env))
+	for _, entry := range env {
+		key, value, ok := strings.Cut(entry, "=")
+		if !ok {
+			continue
+		}
+		result[key] = value
+	}
+	return result
+}
+
 // findTypedValue finds the value of an argument or flag with the specified semantic type.
 // For arguments, it checks the Type field.
 // For flags, it checks the SemanticType field.
 
@@ -24,6 +24,22 @@ import (
 	"github.com/cloudposse/atmos/pkg/schema"
 )
 
+func TestEnvSliceToMap(t *testing.T) {
+	assert.Nil(t, envSliceToMap(nil))
+	assert.Nil(t, envSliceToMap([]string{}))
+	assert.Equal(t, map[string]string{
+		"A":     "override",
+		"B":     "2",
+		"EMPTY": "",
+	}, envSliceToMap([]string{
+		"A=1",
+		"malformed",
+		"B=2",
+		"EMPTY=",
+		"A=override",
+	}))
+}
+
 func TestVerifyInsideGitRepo(t *testing.T) {
 	// Create a temporary directory for testing
 	tmpDir := t.TempDir()
 
@@ -0,0 +1,186 @@
+# PRD: Compose Components
+
+## Summary
+
+Add a `compose` component kind to Atmos. A compose component wraps an existing native
+`compose.*.yaml` project (one or more services, e.g. registry + postgres + k3s) as a single Atmos
+component. It is the bring-your-own / ecosystem-compatible sibling of the
+[container component](container-components.md): Atmos does not reinvent Compose, it runs the project
+and layers Atmos config (env/vars interpolation, secrets, identity/auth, and composition membership)
+on top.
+
+> A component is one unit. To run a *set* of units together as a system, see
+> [compositions](compositions.md).
+
+## Goals
+
+- Operate a native Docker/Podman Compose project as a first-class Atmos component.
+- Keep the Compose file 100% native — Atmos never rewrites Compose syntax.
+- Layer Atmos config on top: variable interpolation, env, secrets, identity, inheritance/catalogs.
+- Provide a deterministic, environment-scoped project name by convention.
+- Participate in compositions via the first-class `composition` membership field.
+
+## Non-Goals
+
+- V1 does not surface Docker Compose `profiles` as an Atmos field or flag (see Deferred). Native
+  `profiles:` inside the user's Compose file still work — Atmos just runs the project.
+- V1 does not translate Compose into another backend; a compose component always runs through the
+  Compose CLI.
+- V1 does not model per-service Atmos identity for services inside the Compose file; the component is
+  the unit of Atmos addressing.
+
+## Public Interface
+
+```yaml
+components:
+  compose:
+    local-infra:
+      composition: storefront            # first-class membership (see compositions.md)
+      metadata:
+        inherits: [compose-defaults]     # catalogs / inheritance like any component
+      files:                             # native compose file(s), untouched
+        - compose.local.yaml
+      project_name: storefront           # OPTIONAL; default = sanitized stack name (see below)
+      env_file:
+        - .env.local
+      vars:                              # interpolated into compose ${...}
+        POSTGRES_VERSION: "16"
+      env:
+        POSTGRES_PASSWORD: !secret pg_password
+```
+
+The referenced `compose.local.yaml` stays native Compose:
+
+```yaml
+# compose.local.yaml
+services:
+  registry:
+    image: registry:2
+    ports: ["5001:5000"]
+  postgres:
+    image: "postgres:${POSTGRES_VERSION}"
+    environment:
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
+    ports: ["5432:5432"]
+  k3s:
+    image: rancher/k3s:latest
+    privileged: true
+    ports: ["6443:6443"]
+```
+
+## Lifecycle
+
+```bash
+atmos compose up local-infra -s local
+atmos compose ps local-infra -s local
+atmos compose logs local-infra postgres -s local
+atmos compose exec local-infra postgres -s local -- psql
+atmos compose restart local-infra -s local
+atmos compose down local-infra -s local
+```
+
+Verb → Compose subcommand mapping:
+
+| atmos verb         | compose command              |
+|--------------------|------------------------------|
+| `up` / `deploy`    | `compose up -d`              |
+| `down` / `destroy` | `compose down` (`--volumes`) |
+| `ps`               | `compose ps`                 |
+| `logs`             | `compose logs [service]`     |
+| `exec`             | `compose exec <svc> -- …`    |
+| `restart`          | `compose restart [service]`  |
+| `build` / `pull`   | `compose build` / `pull`     |
+| `config`           | `compose config` (render)    |
+
+These verbs match the [composition](compositions.md) fan-out so a compose component operates the same
+whether invoked standalone or as a composition member.
+
+## Project Name Convention
+
+`project_name` is a composed convention: derived by default and overridable.
+
+- **Default = the sanitized stack name** (lowercase, `[a-z0-9_-]`, e.g. `plat/ue2-dev` →
+  `plat-ue2-dev`).
+- This makes the Compose project equal to the environment, so `compose ps` / `logs` show the whole
+  local system for that stack together.
+- **Tradeoff**: multiple compose components (or compositions) in one stack share that project
+  namespace — usually desirable for local dev. Set `project_name` explicitly to separate them.
+
+Container components stay per-component (`atmos-<stack>-container-<name>`) because each is one service;
+the compose project groups at the environment level because Compose owns multi-service grouping
+natively.
+
+## `container` vs `compose`
+
+| | `container` component | `compose` component |
+|---|---|---|
+| Unit | One Atmos-native service | A native multi-service Compose project |
+| Lifecycle owner | Atmos (labels, named lifecycle) | Compose CLI |
+| When to use | Atmos-native per-service control | You already have a `compose.yaml` |
+| Grouping | A composition of containers | The Compose project itself |
+
+Both are ordinary stack components with the same component model, membership, and composition fan-out.
+
+## Compose Step (addition to the step library)
+
+Alongside the `compose` component kind, a procedural `type: compose` step **will be added to the shared
+step library** — the inline, ephemeral counterpart, mirroring how `type: container` complements the
+[container component](container-components.md). It is for operating a Compose project as a step inside a
+workflow or custom command (e.g. spin up ephemeral test dependencies, run tests, tear down), without
+modeling it as a stack component.
+
+```yaml
+steps:
+  - name: deps-up
+    type: compose
+    action: up
+    files: [compose.test.yaml]
+    project_name: itest
+
+  - name: integration
+    type: shell
+    command: go test ./it/...
+
+  - name: deps-down
+    type: compose
+    action: down
+    files: [compose.test.yaml]
+    project_name: itest
+```
+
+The step mirrors the component verb mapping (`up`/`down`/`ps`/`logs`/`exec`/`restart`/`build`/`pull`/
+`config`) and the same Docker/Podman runtime detection. Because it is a step, it belongs in the shared
+step library — its full field reference will be specified in
+[Container Actions, Step Outputs, Workflows, and Custom Commands](container-actions-and-step-outputs.md),
+next to `type: container`, not in this component PRD. This keeps the procedural step and the declarative
+component as separate, complementary surfaces.
+
+| Surface              | Shape                          | Use                                   |
+|----------------------|--------------------------------|---------------------------------------|
+| `type: compose` step | Procedural, inline, ephemeral  | Workflow/custom-command Compose ops   |
+| `compose` component  | Declarative, stack-scoped      | Composition member, `atmos compose …` |
+
+## Implementation Notes
+
+- Register `compose` in `schema.Components` and `Components.GetComponentConfig` (sibling of
+  terraform/helmfile/packer/ansible/container).
+- Back the kind with a `pkg/compose` package; re-home the existing `composeArgs()` and
+  `DetectRuntimeWithPreferenceAndRecovery` from `pkg/composition/service.go`.
+- Resolve `vars`/`env` (incl. secrets) into Compose interpolation env and `--env-file`.
+- Default `project_name` to the sanitized stack name when unset.
+- Resolve the first-class `composition` membership field via normal stack processing.
+
+## Deferred
+
+- **Docker Compose profiles**: not surfaced as an Atmos field or flag in V1. "Profile" conflicts with
+  the Atmos / Atmos Pro `--profile` (`ATMOS_PROFILE`) config-profile concept. Native compose-file
+  `profiles:` still work inside the user's Compose file. A general
+  [labels](compositions.md#deferred) concept is the likely future home for this kind of selection.
+
+## Test Plan
+
+- Schema decode tests for the `compose` component kind and `composition` field.
+- Verb → Compose argument construction tests for Docker and Podman.
+- `project_name` default sanitization tests (stack name → valid project name).
+- Variable / env / secret interpolation into Compose invocation.
+- Runtime-gated local smoke test bringing up and tearing down a tiny Compose project.