Merge branch 'main' into copilot/add-description-field-to-components

Author: nitrocode

.claude/agents/gist-creator.md

@@ -0,0 +1,141 @@
+---
+name: gist-creator
+description: >-
+  Expert in creating Atmos gists with proper structure, README documentation,
+  file-browser plugin integration, and blog post announcements.
+
+  **Invoke when:**
+  - User wants to create a new gist
+  - User asks about gist best practices
+  - User wants to add a community recipe or pattern
+  - User mentions "gist" in the context of documentation
+
+tools: Read, Write, Edit, Grep, Glob, Bash, Task, TodoWrite
+model: sonnet
+color: purple
+---
+
+# Gist Creator Agent
+
+Expert in creating well-structured Atmos gists that demonstrate creative combinations of Atmos features.
+
+## What Are Gists?
+
+Gists are community-contributed recipes that show how to combine Atmos features in creative ways. Unlike maintained examples, gists are shared as-is and may not work with current versions of Atmos without adaptations.
+
+## Core Responsibilities
+
+1. Create new gists with proper directory structure
+2. Write comprehensive README documentation
+3. Add tags/docs mappings to the file-browser plugin
+4. Create blog post announcements for new gists
+
+## Gist Directory Structure
+
+Gists live in the `/gists/` directory at the repo root (alongside `/examples/`).
+
+```text
+gists/{name}/
+├── README.md              # Comprehensive guide (REQUIRED)
+├── atmos.yaml             # Atmos configuration (REQUIRED)
+├── .atmos.d/              # Split config files (if applicable)
+│   ├── feature1.yaml
+│   └── feature2.yaml
+├── .mcp.json              # MCP config (if applicable)
+└── stacks/                # Stack configs (if needed)
+```
+
+## README Format
+
+Every gist README.md MUST include:
+
+1. **Title** — Clear, descriptive name as H1
+2. **Overview** — One paragraph explaining the problem and solution
+3. **The Problem** — What pain point this solves
+4. **The Solution** — How Atmos features combine to solve it
+5. **Features Used** — Bulleted list with links to relevant Atmos docs
+6. **How It Works** — Step-by-step explanation of the architecture/flow
+7. **Getting Started** — Prerequisites and setup steps
+8. **Configuration Files** — Table describing each file in the gist
+9. **Usage** — Concrete command examples
+10. **Customization** — How to adapt for different environments
+11. **The Key Insight** — The main takeaway or "aha moment"
+
+## File-Browser Plugin Integration
+
+After creating the gist directory, add entries to `website/plugins/file-browser/index.js`:
+
+### TAGS_MAP
+Add tags for the new gist. Available tags: Quickstart, Stacks, Components, Automation, DX
+
+```js
+'my-gist-name': ['DX', 'Automation'],
+```
+
+### DOCS_MAP
+Add documentation links for the new gist:
+
+```js
+'my-gist-name': [
+  { label: 'Feature Name', url: '/docs/url' },
+],
+```
+
+## Blog Post Announcement
+
+New gists MUST be announced with a blog post in `website/blog/YYYY-MM-DD-gist-slug.mdx`.
+
+IMPORTANT: Only use tags from `website/blog/tags.yml` and authors from `website/blog/authors.yml`.
+
+```mdx
+---
+slug: gist-slug
+title: "Gist: Descriptive Title"
+authors: [author-id] # Must exist in website/blog/authors.yml
+tags: [feature]
+---
+
+Brief intro about the gist.
+
+<!--truncate-->
+
+## What This Gist Does
+[Description]
+
+## Features Used
+[List of Atmos features combined]
+
+## Try It Out
+[Link to /gists/name]
+
+## Get Involved
+- Browse the [Gists collection](/gists)
+- [Join us on Slack](/community/slack)
+- [Attend Office Hours](/community/office-hours)
+```
+
+## Key Differences from Examples
+
+| | Examples | Gists |
+|---|---|---|
+| **Location** | `/examples/` | `/gists/` |
+| **Maintained** | Yes, tested each release | No, shared as-is |
+| **Scope** | Single feature | Multiple features combined |
+| **Disclaimer** | None | GistDisclaimer shown via file-browser plugin |
+| **Style** | Minimal config files | Rich README + config files |
+
+## GistDisclaimer Component
+
+The disclaimer is automatically shown on all gist pages by the file-browser plugin (configured via the `disclaimer` option in `website/docusaurus.config.js`). No manual inclusion needed in gist files.
+
+The component is at `website/src/components/GistDisclaimer/` and accepts a `text` prop.
+
+## Verification Checklist
+
+After creating a gist:
+1. `gists/{name}/README.md` exists and is comprehensive
+2. `gists/{name}/atmos.yaml` exists
+3. Tags added to TAGS_MAP in `website/plugins/file-browser/index.js`
+4. Docs added to DOCS_MAP in `website/plugins/file-browser/index.js`
+5. Blog post created in `website/blog/`
+6. Website builds successfully: `cd website && npm run build`

cmd/auth_exec.go

@@ -110,24 +110,17 @@ func executeAuthExecCommandCore(cmd *cobra.Command, args []string) error {
 
 	// Prepare shell environment with file-based credentials.
 	// Start with current OS environment + global env from atmos.yaml and let PrepareShellEnvironment configure auth.
+	// PrepareShellEnvironment sanitizes the env (removes IRSA/credential vars) and adds auth vars.
 	baseEnv := envpkg.MergeGlobalEnv(os.Environ(), atmosConfig.Env)
 	envList, err := authManager.PrepareShellEnvironment(ctx, identityName, baseEnv)
 	if err != nil {
 		return fmt.Errorf("failed to prepare command environment: %w", err)
 	}
 
-	// Convert environment list to map for executeCommandWithEnv.
-	envMap := make(map[string]string)
-	for _, envVar := range envList {
-		if idx := strings.IndexByte(envVar, '='); idx >= 0 {
-			key := envVar[:idx]
-			value := envVar[idx+1:]
-			envMap[key] = value
-		}
-	}
-
-	// Execute the command with authentication environment.
-	err = executeCommandWithEnv(commandArgs, envMap)
+	// Execute the command with the sanitized environment directly.
+	// The envList already includes os.Environ() (sanitized) + auth vars,
+	// so we pass it as the complete subprocess environment.
+	err = executeCommandWithEnv(commandArgs, envList)
 	if err != nil {
 		// For any subprocess error, provide a tip about refreshing credentials.
 		// This helps users when AWS tokens are expired or invalid.
@@ -137,29 +130,25 @@ func executeAuthExecCommandCore(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-// executeCommandWithEnv executes a command with additional environment variables.
-func executeCommandWithEnv(args []string, envVars map[string]string) error {
+// executeCommandWithEnv executes a command with a complete environment.
+// The env parameter should be a fully prepared environment (e.g., from PrepareShellEnvironment).
+// It is used directly as the subprocess environment without re-reading os.Environ().
+func executeCommandWithEnv(args []string, env []string) error {
 	if len(args) == 0 {
 		return fmt.Errorf(errUtils.ErrWrapFormat, errUtils.ErrNoCommandSpecified, errUtils.ErrInvalidSubcommand)
 	}
 
-	// Prepare the command
+	// Prepare the command.
 	cmdName := args[0]
 	cmdArgs := args[1:]
 
-	// Look for the command in PATH
+	// Look for the command in PATH.
 	cmdPath, err := exec.LookPath(cmdName)
 	if err != nil {
 		return fmt.Errorf(errUtils.ErrWrapFormat, errUtils.ErrCommandNotFound, err)
 	}
 
-	// Prepare environment variables
-	env := os.Environ()
-	for key, value := range envVars {
-		env = append(env, fmt.Sprintf("%s=%s", key, value))
-	}
-
-	// Execute the command
+	// Execute the command with the provided environment directly.
 	execCmd := exec.Command(cmdPath, cmdArgs...)
 	execCmd.Env = env
 	execCmd.Stdin = os.Stdin

cmd/auth_exec_test.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"bytes"
 	"errors"
+	"os"
 	"runtime"
 	"testing"
 
@@ -218,52 +219,57 @@ func TestExtractIdentityFlag(t *testing.T) {
 }
 
 func TestExecuteCommandWithEnv(t *testing.T) {
+	// Use the test binary itself as a cross-platform subprocess helper.
+	// TestMain in testing_main_test.go handles _ATMOS_TEST_EXIT_ONE.
+	exePath, err := os.Executable()
+	require.NoError(t, err, "os.Executable() must succeed")
+
+	// Prerequisite: verify that env vars reach the child process.
+	t.Run("env propagation to subprocess", func(t *testing.T) {
+		// Running the test binary with -test.run=^$ matches no tests and exits 0,
+		// confirming the subprocess receives the provided environment.
+		err := executeCommandWithEnv(
+			[]string{exePath, "-test.run=^$"},
+			[]string{"TEST_VAR=test-value"},
+		)
+		assert.NoError(t, err)
+	})
+
 	// Test the command execution helper directly.
 	tests := []struct {
 		name          string
 		args          []string
-		envVars       map[string]string
-		skipOnWindows bool
+		envVars       []string
 		expectedError string
-		expectedCode  int // Expected exit code if error is ExitCodeError
+		expectedCode  int // Expected exit code if error is ExitCodeError.
 	}{
 		{
 			name:          "empty args",
 			args:          []string{},
-			envVars:       map[string]string{},
+			envVars:       []string{},
 			expectedError: "no command specified",
 		},
 		{
-			name: "simple echo command",
-			args: []string{"echo", "hello"},
-			envVars: map[string]string{
-				"TEST_VAR": "test-value",
-			},
-			skipOnWindows: true,
+			name:    "successful command",
+			args:    []string{exePath, "-test.run=^$"},
+			envVars: []string{"TEST_VAR=test-value"},
 		},
 		{
 			name:          "nonexistent command",
 			args:          []string{"nonexistent-command-xyz"},
-			envVars:       map[string]string{},
+			envVars:       []string{},
 			expectedError: "command not found",
 		},
 		{
-			name: "command with non-zero exit code",
-			args: []string{"sh", "-c", "exit 2"},
-			envVars: map[string]string{
-				"TEST_VAR": "test-value",
-			},
-			skipOnWindows: true,
-			expectedCode:  2,
+			name:         "command with non-zero exit code",
+			args:         []string{exePath, "-test.run=^$"},
+			envVars:      []string{"_ATMOS_TEST_EXIT_ONE=1"},
+			expectedCode: 1,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			if tt.skipOnWindows && runtime.GOOS == "windows" {
-				t.Skipf("Skipping test on Windows: command behaves differently")
-			}
-
 			err := executeCommandWithEnv(tt.args, tt.envVars)
 
 			switch {
@@ -274,7 +280,7 @@ func TestExecuteCommandWithEnv(t *testing.T) {
 				}
 			case tt.expectedCode != 0:
 				assert.Error(t, err)
-				// Check that it's an ExitCodeError with the correct code
+				// Check that it's an ExitCodeError with the correct code.
 				var exitCodeErr errUtils.ExitCodeError
 				if assert.True(t, errors.As(err, &exitCodeErr), "error should be ExitCodeError") {
 					assert.Equal(t, tt.expectedCode, exitCodeErr.Code)

cmd/auth_shell.go

@@ -115,6 +115,7 @@ func executeAuthShellCommandCore(cmd *cobra.Command, args []string) error {
 
 	// Prepare shell environment with file-based credentials.
 	// Start with current OS environment and let PrepareShellEnvironment configure auth.
+	// PrepareShellEnvironment sanitizes the env (removes IRSA/credential vars) and adds auth vars.
 	envList, err := authManager.PrepareShellEnvironment(ctx, identityName, os.Environ())
 	if err != nil {
 		return fmt.Errorf("failed to prepare shell environment: %w", err)
@@ -129,18 +130,9 @@ func executeAuthShellCommandCore(cmd *cobra.Command, args []string) error {
 	// Get provider name from the identity to display in shell messages.
 	providerName := authManager.GetProviderForIdentity(identityName)
 
-	// Execute the shell with authentication environment.
-	// ExecAuthShellCommand expects env vars as a map, so convert the list.
-	envMap := make(map[string]string)
-	for _, envVar := range envList {
-		if idx := strings.IndexByte(envVar, '='); idx >= 0 {
-			key := envVar[:idx]
-			value := envVar[idx+1:]
-			envMap[key] = value
-		}
-	}
-
-	return exec.ExecAuthShellCommand(atmosConfigPtr, identityName, providerName, envMap, shell, shellArgs)
+	// Execute the shell with the sanitized environment directly.
+	// envList already includes os.Environ() (sanitized) + auth vars.
+	return exec.ExecAuthShellCommand(atmosConfigPtr, identityName, providerName, envList, shell, shellArgs)
 }
 
 // extractAuthShellFlags extracts --identity and --shell flags from args and returns the remaining shell args.

cmd/list/affected.go

@@ -5,6 +5,7 @@ import (
 	"github.com/spf13/viper"
 
 	e "github.com/cloudposse/atmos/internal/exec"
+	cfg "github.com/cloudposse/atmos/pkg/config"
 	"github.com/cloudposse/atmos/pkg/flags"
 	"github.com/cloudposse/atmos/pkg/flags/global"
 	"github.com/cloudposse/atmos/pkg/list"
@@ -39,6 +40,9 @@ type AffectedOptions struct {
 	ProcessTemplates bool
 	ProcessFunctions bool
 	Skip             []string
+
+	// Auth flags.
+	IdentityName string
 }
 
 // affectedCmd lists affected Atmos components and stacks.
@@ -59,6 +63,15 @@ var affectedCmd = &cobra.Command{
 			return err
 		}
 
+		// Read identity from flag (inherited from listCmd PersistentFlags) or env var.
+		var identityName string
+		if cmd.Flags().Changed(cfg.IdentityFlagName) {
+			identityName, _ = cmd.Flags().GetString(cfg.IdentityFlagName)
+		} else {
+			identityName = v.GetString(cfg.IdentityFlagName)
+		}
+		identityName = cfg.NormalizeIdentityValue(identityName)
+
 		opts := &AffectedOptions{
 			Flags:             flags.ParseGlobalFlags(cmd, v),
 			Format:            v.GetString("format"),
@@ -77,6 +90,7 @@ var affectedCmd = &cobra.Command{
 			ProcessTemplates:  v.GetBool("process-templates"),
 			ProcessFunctions:  v.GetBool("process-functions"),
 			Skip:              v.GetStringSlice("skip"),
+			IdentityName:      identityName,
 		}
 
 		return executeListAffectedCmd(cmd, args, opts)
@@ -147,5 +161,6 @@ func executeListAffectedCmd(cmd *cobra.Command, args []string, opts *AffectedOpt
 		ProcessFunctions:  opts.ProcessFunctions,
 		Skip:              opts.Skip,
 		ExcludeLocked:     opts.ExcludeLocked,
+		IdentityName:      opts.IdentityName,
 	})
 }