Support Atmos Toolchain for 3rd Party Tools

.gitignore

@@ -93,14 +93,23 @@ tools/gomodcheck/.gomodcheck
 # Claude Code and Hive Mind development tools
 .claude-flow/
 .hive-mind/
+.claude/plans/
 
 performance-optimization/
+node_modules
+
+# Toolchain installed tools
+.tools/
+toolchain/.tools/
+toolchain/.tool-versions
 
 # Merge conflict artifacts and backup files
 *.orig
 *.rej
 .scratch
 *.bak
+*.bak[0-9]
+*.bak[0-9][0-9]
 *.go.bak
 **/*.go.bak
 
@@ -110,4 +119,10 @@ TEST_FAILURE_ANALYSIS.md
 scratch/
 COVERAGE_SUMMARY.md
 TESTABILITY_CHANGES_SUMMARY.md
+
+# Conductor scratch/temporary files
+*.log
+*_progress.txt
+*_summary.txt
+reply_to_*.sh
 *.ansi

CLAUDE.md

@@ -316,6 +316,14 @@ ALWAYS build the website after documentation changes: `cd website && npm run bui
 ### Git (MANDATORY)
 Don't commit: todos, research, scratch files. Do commit: code, tests, requested docs, schemas. Update `.gitignore` for patterns only.
 
+**NEVER run destructive git commands without explicit user confirmation:**
+- `git reset HEAD` or `git reset --hard` - discards staged/committed changes
+- `git checkout HEAD -- .` or `git checkout -- .` - discards all working changes
+- `git clean -fd` - deletes untracked files
+- `git stash drop` - permanently deletes stashed changes
+
+Always ask first: "This will discard uncommitted changes. Proceed? [y/N]"
+
 ### Test Coverage (MANDATORY)
 80% minimum (CodeCov enforced). All features need tests. `make testacc-coverage` for reports.
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2020-2025 Cloud Posse, LLC
+   Copyright 2020-2026 Cloud Posse, LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

cmd/auth_login_test.go

@@ -487,6 +487,7 @@ func TestIdentitySelectorBehavior(t *testing.T) {
 			// will check flag first, then fall back to viper.
 
 			// Set viper value if needed to simulate config/env values.
+			// Clean up viper value after subtest to prevent pollution.
 			if tt.setViperValue {
 				viper.Set(IdentityFlagName, tt.viperIdentityValue)
 				t.Cleanup(func() {

cmd/auth_shell_test.go

@@ -1,13 +1,15 @@
 package cmd
 
 import (
+	"path/filepath"
 	"runtime"
 	"testing"
 
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	errUtils "github.com/cloudposse/atmos/errors"
 	"github.com/cloudposse/atmos/pkg/auth/identities/aws"
 )
 
@@ -21,47 +23,49 @@ func disableAWSCredentialPrompting(t *testing.T) {
 }
 
 func TestAuthShellCmd_FlagParsing(t *testing.T) {
+	// Use TestKit to ensure proper test isolation.
+	_ = NewTestKit(t)
 	disableAWSCredentialPrompting(t)
 
 	tests := []struct {
-		name          string
-		args          []string
-		expectedError string
+		name                string
+		args                []string
+		expectedSentinelErr error // The specific sentinel error expected
 	}{
 		{
 			name: "no identity specified uses default",
 			args: []string{},
-			// This will fail with auth errors since we don't have real AWS SSO configured.
-			expectedError: "authentication failed",
+			// Fixture has test-admin as default. Will fail at authentication since we don't have real AWS SSO.
+			expectedSentinelErr: errUtils.ErrAuthenticationFailed,
 		},
 		{
-			name:          "nonexistent identity",
-			args:          []string{"--identity=nonexistent"},
-			expectedError: "identity not found",
+			name:                "nonexistent identity",
+			args:                []string{"--identity=nonexistent"},
+			expectedSentinelErr: errUtils.ErrIdentityNotFound,
 		},
 		{
 			name: "valid identity",
 			args: []string{"--identity=test-user"},
-			// This will fail with auth errors since we don't have real AWS credentials.
-			expectedError: "authentication failed",
+			// This will fail at authentication since we don't have real AWS credentials.
+			expectedSentinelErr: errUtils.ErrAuthenticationFailed,
 		},
 		{
 			name: "shell override flag",
 			args: []string{"--shell", "/bin/bash"},
-			// This will fail with auth errors since we don't have real AWS credentials.
-			expectedError: "authentication failed",
+			// Fixture has test-admin as default. Will fail at authentication since we don't have real AWS SSO.
+			expectedSentinelErr: errUtils.ErrAuthenticationFailed,
 		},
 		{
 			name: "shell args after double dash",
 			args: []string{"--", "-c", "echo test"},
-			// This will fail with auth errors since we don't have real AWS credentials.
-			expectedError: "authentication failed",
+			// Fixture has test-admin as default. Will fail at authentication since we don't have real AWS SSO.
+			expectedSentinelErr: errUtils.ErrAuthenticationFailed,
 		},
 		{
 			name: "identity with shell args",
 			args: []string{"--identity=test-user", "--", "-c", "env"},
-			// This will fail with auth errors since we don't have real AWS credentials.
-			expectedError: "authentication failed",
+			// This will fail at authentication since we don't have real AWS credentials.
+			expectedSentinelErr: errUtils.ErrAuthenticationFailed,
 		},
 	}
 
@@ -82,11 +86,11 @@ func TestAuthShellCmd_FlagParsing(t *testing.T) {
 			// Call the core business logic directly, bypassing handleHelpRequest and checkAtmosConfig.
 			err := executeAuthShellCommandCore(testCmd, tt.args)
 
-			if tt.expectedError != "" {
-				assert.Error(t, err)
-				if err != nil {
-					assert.Contains(t, err.Error(), tt.expectedError)
-				}
+			if tt.expectedSentinelErr != nil {
+				require.Error(t, err, "Expected an error but got nil")
+				assert.ErrorIs(t, err, tt.expectedSentinelErr,
+					"Expected error chain to contain %v, but got: %v",
+					tt.expectedSentinelErr, err)
 			} else {
 				assert.NoError(t, err)
 			}
@@ -95,6 +99,8 @@ func TestAuthShellCmd_FlagParsing(t *testing.T) {
 }
 
 func TestAuthShellCmd_CommandStructure(t *testing.T) {
+	_ = NewTestKit(t)
+
 	// Test that the real authShellCmd has the expected structure.
 	assert.Equal(t, "shell", authShellCmd.Use)
 	assert.True(t, authShellCmd.DisableFlagParsing, "DisableFlagParsing should be true to allow pass-through of shell arguments")
@@ -113,6 +119,7 @@ func TestAuthShellCmd_CommandStructure(t *testing.T) {
 }
 
 func TestAuthShellCmd_InvalidFlagHandling(t *testing.T) {
+	_ = NewTestKit(t)
 	disableAWSCredentialPrompting(t)
 
 	// Set up test fixture.
@@ -136,7 +143,9 @@ func TestAuthShellCmd_EmptyEnvVars(t *testing.T) {
 
 	// Test that the command handles nil environment variables gracefully.
 	// This tests the path where envVars is nil and gets initialized to empty map.
-	testDir := "../tests/fixtures/scenarios/atmos-auth"
+	testDir, err := filepath.Abs("../tests/fixtures/scenarios/atmos-auth")
+	require.NoError(t, err, "Failed to get absolute path to test fixture")
+
 	t.Setenv("ATMOS_CLI_CONFIG_PATH", testDir)
 	t.Setenv("ATMOS_BASE_PATH", testDir)
 
@@ -147,13 +156,16 @@ func TestAuthShellCmd_EmptyEnvVars(t *testing.T) {
 	testCmd.Flags().AddFlagSet(authShellCmd.Flags())
 
 	// This will fail at authentication but will exercise the env var initialization path.
-	err := executeAuthShellCommandCore(testCmd, []string{"--identity=test-user"})
-	assert.Error(t, err)
-	// Should contain authentication failed, not nil pointer errors.
-	assert.Contains(t, err.Error(), "authentication failed")
+	err = executeAuthShellCommandCore(testCmd, []string{"--identity=test-user"})
+	// Should be an authentication error, not nil pointer errors.
+	require.Error(t, err, "Expected an error but got nil")
+	assert.ErrorIs(t, err, errUtils.ErrAuthenticationFailed,
+		"Expected ErrAuthenticationFailed, but got: %v", err)
 }
 
 func TestAuthShellCmd_HelpRequest(t *testing.T) {
+	_ = NewTestKit(t)
+
 	// Test that the command handles help request arguments.
 	// When DisableFlagParsing is true, Cobra doesn't add the help flag automatically,
 	// so handleHelpRequest in cmd/helpers.go handles --help and -h manually.
@@ -170,6 +182,8 @@ func TestAuthShellCmd_HelpRequest(t *testing.T) {
 }
 
 func TestAuthShellCmd_ShellEnvironmentBinding(t *testing.T) {
+	_ = NewTestKit(t)
+
 	// Test that SHELL and ATMOS_SHELL environment variables are bound.
 	// This verifies the init() function's viper bindings work correctly.
 	testShell := "/bin/test-shell"
@@ -186,6 +200,8 @@ func TestAuthShellCmd_ShellEnvironmentBinding(t *testing.T) {
 }
 
 func TestAuthShellCmd_WithMockProvider(t *testing.T) {
+	_ = NewTestKit(t)
+
 	if testing.Short() {
 		t.Skipf("Skipping integration test in short mode: spawns actual shell process")
 	}
@@ -228,6 +244,8 @@ func TestAuthShellCmd_WithMockProvider(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
+			_ = NewTestKit(t)
+
 			// Set up mock auth provider fixture for each subtest.
 			testDir := "../tests/fixtures/scenarios/atmos-auth-mock"
 			t.Setenv("ATMOS_CLI_CONFIG_PATH", testDir)
@@ -251,6 +269,8 @@ func TestAuthShellCmd_WithMockProvider(t *testing.T) {
 }
 
 func TestAuthShellCmd_MockProviderEnvironmentVariables(t *testing.T) {
+	_ = NewTestKit(t)
+
 	if testing.Short() {
 		t.Skipf("Skipping integration test in short mode: spawns actual shell process")
 	}

cmd/auth_whoami.go

@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"os"
 	"strings"
@@ -17,6 +16,7 @@ import (
 	authTypes "github.com/cloudposse/atmos/pkg/auth/types"
 	cfg "github.com/cloudposse/atmos/pkg/config"
 	"github.com/cloudposse/atmos/pkg/config/homedir"
+	"github.com/cloudposse/atmos/pkg/data"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/schema"
 	"github.com/cloudposse/atmos/pkg/ui"
@@ -161,13 +161,10 @@ func printWhoamiJSON(whoami *authTypes.WhoamiInfo) error {
 	if whoami.Environment != nil {
 		redactedWhoami.Environment = sanitizeEnvMap(whoami.Environment, homeDir)
 	}
-	jsonData, err := json.MarshalIndent(redactedWhoami, "", "  ")
-	if err != nil {
-		errUtils.CheckErrorAndPrint(errUtils.ErrInvalidAuthConfig, "Failed to marshal JSON", "")
-		return errUtils.ErrInvalidAuthConfig
-	}
-	fmt.Println(string(jsonData))
-	return nil
+	// Use data.WriteJSON() to write to the data channel (stdout) with proper I/O handling.
+	// This ensures output goes through the I/O layer with automatic masking and respects
+	// stream redirection in tests.
+	return data.WriteJSON(redactedWhoami)
 }
 
 func printWhoamiHuman(whoami *authTypes.WhoamiInfo, isValid bool) {

cmd/cmd_utils.go

@@ -24,6 +24,7 @@ import (
 	"github.com/cloudposse/atmos/pkg/auth/credentials"
 	"github.com/cloudposse/atmos/pkg/auth/validation"
 	cfg "github.com/cloudposse/atmos/pkg/config"
+	"github.com/cloudposse/atmos/pkg/dependencies"
 	envpkg "github.com/cloudposse/atmos/pkg/env"
 	l "github.com/cloudposse/atmos/pkg/list"
 	log "github.com/cloudposse/atmos/pkg/logger"
@@ -430,6 +431,26 @@ func executeCustomCommand(
 		finalArgs = args
 	}
 
+	// Resolve and install command dependencies
+	resolver := dependencies.NewResolver(&atmosConfig)
+	deps, err := resolver.ResolveCommandDependencies(commandConfig)
+	if err != nil {
+		errUtils.CheckErrorPrintAndExit(err, "", fmt.Sprintf("Failed to resolve dependencies for command '%s'", commandConfig.Name))
+	}
+
+	if len(deps) > 0 {
+		log.Debug("Installing command dependencies", "command", commandConfig.Name, "tools", deps)
+		installer := dependencies.NewInstaller(&atmosConfig)
+		if err := installer.EnsureTools(deps); err != nil {
+			errUtils.CheckErrorPrintAndExit(err, "", fmt.Sprintf("Failed to install dependencies for command '%s'", commandConfig.Name))
+		}
+
+		// Update PATH to include installed tools
+		if err := dependencies.UpdatePathForTools(&atmosConfig, deps); err != nil {
+			errUtils.CheckErrorPrintAndExit(err, "", fmt.Sprintf("Failed to update PATH for command '%s'", commandConfig.Name))
+		}
+	}
+
 	// Create auth manager if identity is specified for this custom command.
 	// Check for --identity flag first (it overrides the config).
 	var authManager auth.AuthManager
@@ -806,6 +827,31 @@ func isVersionCommand() bool {
 	return len(os.Args) > 1 && (os.Args[1] == "version" || os.Args[1] == "--version")
 }
 
+// isVersionManagementCommand checks if the current command is a version management command.
+// These commands should not trigger re-exec to avoid infinite loops.
+func isVersionManagementCommand(cmd *cobra.Command) bool {
+	if cmd == nil {
+		return false
+	}
+
+	// Check the command hierarchy.
+	cmdName := cmd.Name()
+
+	// Direct version subcommands that manage local installations (install, uninstall).
+	// Note: "list" is excluded because it can reasonably work with --use-version
+	// to list releases using a different Atmos version.
+	if cmd.Parent() != nil && cmd.Parent().Name() == "version" {
+		return cmdName == "install" || cmdName == "uninstall"
+	}
+
+	// The version command itself (shows current version).
+	if cmdName == "version" && cmd.Parent() != nil && cmd.Parent().Name() == "atmos" {
+		return true
+	}
+
+	return false
+}
+
 // handleHelpRequest shows help content and exits only if the first argument is "help" or "--help" or "-h".
 func handleHelpRequest(cmd *cobra.Command, args []string) {
 	if (len(args) > 0 && args[0] == "help") || Contains(args, "--help") || Contains(args, "-h") {

cmd/describe_affected_test.go

@@ -26,6 +26,12 @@ func TestDescribeAffected(t *testing.T) {
 	t.Setenv("IDENTITY", "")
 
 	t.Chdir("../tests/fixtures/scenarios/basic")
+
+	// Disable authentication for this test to prevent validation errors.
+	// Set both environment variable and viper value to ensure it's recognized.
+	t.Setenv("ATMOS_IDENTITY", "false")
+	viper.Set("identity", "false")
+
 	ctrl := gomock.NewController(t)
 	defer ctrl.Finish()
 

cmd/help_template.go

@@ -371,7 +371,10 @@ func printDescription(w io.Writer, cmd *cobra.Command, styles *helpStyles) {
 	// Use markdown rendering to respect terminal width and wrapping settings.
 	// This ensures long descriptions wrap properly based on screen width.
 	rendered := renderMarkdownDescription(desc)
-	fmt.Fprintln(w, styles.commandDesc.Render(rendered))
+	styled := styles.commandDesc.Render(rendered)
+	// Lipgloss pads multi-line strings to uniform width. Trim trailing whitespace from each line.
+	styled = ui.TrimLinesRight(styled)
+	fmt.Fprintln(w, styled)
 	fmt.Fprintln(w)
 }
 

cmd/markdown/atmos_toolchain_add.md

@@ -0,0 +1,9 @@
+- Add a tool with version
+```
+ $ atmos toolchain add <tool-name> <version>
+```
+
+- Use a custom tool versions file
+```
+ $ atmos toolchain add --file <path/to/.tool-versions> <tool-name> <version>
+```

cmd/markdown/atmos_toolchain_aliases.md

@@ -0,0 +1,4 @@
+- Get the aliases configured
+```
+ $ atmos toolchain aliases
+```

cmd/markdown/atmos_toolchain_clean.md

@@ -0,0 +1,5 @@
+- Delete everything from toolchain
+
+```
+ $ atmos toolchain clean
+```