📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Generate mocks with go.uber.org/mock/mockgen using //go:generate directives; never write manual mocks
Use functional options pattern instead of functions with many parameters
Use context.Context only for cancellation, deadlines, and narrowly-scoped request values; never for config or dependencies; context should be the first parameter
All comments must end with periods (godot linter)
Organize imports in three groups with blank lines (stdlib, third-party, then Atmos packages) and sort alphabetically; keep aliases: cfg, log, u, errUtils
Error handling: wrap with static errors from errors/errors.go, combine with errors.Join, add context with fmt.Errorf("%w: msg", err), check with errors.Is; never compare strings or create dynamic error types
Use //go:generate go run go.uber.org/mock/mockgen@latest -source= -destination=test.go for mocks
Keep files small and focused (<600 lines), one command/impl per file; co-locate tests; never use //revive:disable:file-length-limit
Bind environment variables with viper.BindEnv and use ATMOS prefix
UI (prompts/status) must write to stderr; data outputs to stdout; logging only for system events, not UI
Ensure cross-platform compatibility: prefer SDKs over binaries and use filepath.Join() instead of hardcoded separators

Files:

• internal/exec/terraform.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/manager.go
• pkg/auth/credentials/keyring_noop.go
• internal/exec/terraform_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• internal/exec/terraform.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/manager.go
• pkg/auth/credentials/keyring_noop.go

📄 CodeRabbit inference engine (CLAUDE.md)

{internal,pkg}/**/*.go: Use interface-driven design: define interfaces, inject dependencies for testability, and prefer DI over concrete coupling
Add defer perf.Track(atmosConfig, "pkg.FuncName")() + a blank line at the start of all public functions (use nil if no atmosConfig)

Files:

• internal/exec/terraform.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/manager.go
• pkg/auth/credentials/keyring_noop.go
• internal/exec/terraform_test.go

📄 CodeRabbit inference engine (CLAUDE.md)

Implement command business logic in internal/exec/ (not in cmd/)

Files:

• internal/exec/terraform.go
• internal/exec/terraform_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/manager.go
• pkg/auth/credentials/keyring_noop.go

📄 CodeRabbit inference engine (CLAUDE.md)

Create purpose-built, focused packages under pkg/ instead of adding to utils; co-locate tests with clear responsibilities

Files:

• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/manager.go
• pkg/auth/credentials/keyring_noop.go

📄 CodeRabbit inference engine (CLAUDE.md)

Prefer unit tests with mocks over integration; table-driven tests; keep integration tests under tests/; target >80% coverage

Files:

• tests/fixtures/scenarios/atmos-auth-invalid/atmos.yaml
• internal/exec/terraform_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests
Test both happy paths and error conditions
Use table-driven tests for multiple scenarios

**/*_test.go: Test behavior, not implementation; avoid tautological tests; use DI to make behavior testable
Tests must exercise production code paths; do not duplicate logic in tests
Use t.Skipf("reason") with clear context when skipping tests

Files:

• internal/exec/terraform_test.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: internal/exec/terraform.go:269-272
Timestamp: 2025-10-03T18:02:08.535Z
Learning: In internal/exec/terraform.go, when auth.TerraformPreHook fails, the error is logged but execution continues. This is a deliberate design choice to allow Terraform commands to proceed even if authentication setup fails, rather than failing fast.

Applied to files:

• internal/exec/terraform.go
• internal/exec/terraform_test.go

Learnt from: samtholiya
PR: cloudposse/atmos#1466
File: toolchain/list.go:39-42
Timestamp: 2025-09-13T18:06:07.674Z
Learning: In the cloudposse/atmos repository, for UI messages in the toolchain package, use utils.PrintfMessageToTUI instead of log.Error or fmt.Fprintln(os.Stderr, ...). Import pkg/utils with alias "u" to follow the established pattern.

Applied to files:

• pkg/auth/manager.go

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

pkg/auth/credentials/keyring_file.go (1)

• ErrCredentialsNotFound (36-36)

pkg/logger/log.go (1)

• Debug (24-26)

errors/errors.go (1)

• ErrNoCredentialsFound (386-386)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/auth/types/interfaces.go (2)

• Provider (13-42)
• Identity (45-69)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/auth/cloud/aws/env.go (1)

• LoadAtmosManagedAWSConfig (142-176)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/schema/schema.go (1)

• ConfigAndStacksInfo (488-567)

internal/exec/terraform.go (1)

• ExecuteTerraform (33-623)

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/auth/identities/aws/permission_set.go
• pkg/auth/credentials/keyring_noop.go
• pkg/xdg/xdg.go
• pkg/auth/providers/mock/identity_test.go
• pkg/auth/identities/aws/assume_role_test.go
• pkg/auth/providers/aws/sso_test.go
• pkg/auth/providers/mock/credentials.go
• pkg/xdg/xdg_test.go
• pkg/auth/identities/aws/user_test.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/credentials/store_test.go
• pkg/auth/providers/mock/identity.go
• pkg/auth/identities/aws/permission_set_test.go
• pkg/auth/types/github_oidc_credentials.go
• pkg/auth/manager.go
• pkg/auth/cloud/aws/files.go
• pkg/auth/providers/aws/saml_test.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/cloud/aws/setup_test.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• pkg/auth/hooks_test.go
• pkg/auth/credentials/keyring_file_test.go
• pkg/auth/identities/aws/assume_role.go
• pkg/auth/cloud/aws/files_test.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/types/interfaces.go
• pkg/auth/manager_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Define interfaces for major functionality and use dependency injection to enable testability.
Generate mocks using go.uber.org/mock/mockgen via //go:generate directives (never manual mocks).
Prefer functional Options pattern instead of functions with many parameters for configuration.
Use context.Context only for cancellation, deadlines/timeouts, and request-scoped values; never for configuration or dependencies; context should be the first parameter.
All comments must end with periods (godot linter).
Preserve helpful existing comments; update them to match code when refactoring; only remove when incorrect, redundant, or code removed.
Organize imports in three groups (stdlib, third-party, Atmos) separated by blank lines and sorted alphabetically; maintain aliases cfg, log, u, errUtils.
Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.
Use static errors from errors/errors.go; wrap with fmt.Errorf("%w") for chaining; use errors.Join for independent errors; avoid dynamic errors and string comparison; use errors.Is for checks.
Never use //revive:disable:file-length-limit to bypass file size limits; keep files small and focused (<600 lines).
Environment variables must be bound with viper.BindEnv using ATMOS_ prefix (e.g., viper.BindEnv("ATMOS_VAR", "ATMOS_VAR", "FALLBACK")).
Ensure cross-platform compatibility: use filepath.Join instead of hardcoded path separators and prefer SDKs over shelling out to binaries.

Files:

• pkg/auth/identities/aws/permission_set.go
• pkg/auth/credentials/keyring_noop.go
• pkg/xdg/xdg.go
• internal/exec/yaml_func_terraform_output_test.go
• pkg/auth/providers/mock/identity_test.go
• pkg/auth/identities/aws/assume_role_test.go
• pkg/auth/providers/aws/sso_test.go
• pkg/auth/providers/mock/credentials.go
• pkg/xdg/xdg_test.go
• pkg/auth/identities/aws/user_test.go
• internal/exec/terraform_output_utils.go
• internal/aws_utils/aws_utils.go
• pkg/auth/identities/aws/credentials_loader_test.go
• internal/exec/yaml_func_utils.go
• pkg/auth/cloud/aws/env.go
• pkg/auth/credentials/store_test.go
• cmd/auth_console_test.go
• cmd/auth_whoami.go
• pkg/auth/providers/mock/identity.go
• pkg/auth/identities/aws/permission_set_test.go
• pkg/auth/types/github_oidc_credentials.go
• internal/exec/mock_terraform_output_getter.go
• internal/exec/template_funcs_component.go
• pkg/auth/manager.go
• pkg/auth/cloud/aws/files.go
• internal/exec/yaml_func_terraform_output_authcontext_test.go
• pkg/auth/providers/aws/saml_test.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/cloud/aws/setup_test.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• cmd/auth_env.go
• pkg/auth/hooks_test.go
• internal/exec/terraform_output_getter.go
• pkg/auth/credentials/keyring_file_test.go
• pkg/auth/identities/aws/assume_role.go
• internal/exec/yaml_func_terraform_output.go
• pkg/auth/cloud/aws/files_test.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/types/interfaces.go
• pkg/auth/manager_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• pkg/auth/identities/aws/permission_set.go
• pkg/auth/credentials/keyring_noop.go
• pkg/xdg/xdg.go
• pkg/auth/providers/mock/credentials.go
• internal/exec/terraform_output_utils.go
• internal/aws_utils/aws_utils.go
• internal/exec/yaml_func_utils.go
• pkg/auth/cloud/aws/env.go
• cmd/auth_whoami.go
• pkg/auth/providers/mock/identity.go
• pkg/auth/types/github_oidc_credentials.go
• internal/exec/mock_terraform_output_getter.go
• internal/exec/template_funcs_component.go
• pkg/auth/manager.go
• pkg/auth/cloud/aws/files.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/identities/aws/user.go
• pkg/auth/types/aws_credentials.go
• cmd/auth_env.go
• internal/exec/terraform_output_getter.go
• pkg/auth/identities/aws/assume_role.go
• internal/exec/yaml_func_terraform_output.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/types/interfaces.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases

Files:

• website/docs/cli/commands/auth/auth-shell.mdx
• website/docs/cli/commands/auth/logout.mdx
• website/docs/cli/commands/auth/usage.mdx
• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• website/blog/2025-10-21-auth-context-implementation.md
• website/docs/cli/commands/auth/tutorials/configuring-geodesic.mdx

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests
Test both happy paths and error conditions
Use table-driven tests for multiple scenarios

**/*_test.go: Prefer unit tests with mocks over integration tests; use interfaces + DI; table-driven tests for coverage; target >80% coverage.
Tests must exercise production code paths; avoid duplicating implementation logic in tests.
Use t.Skipf("reason") with clear context when skipping tests; CLI tests may auto-build temp binaries.

Files:

• internal/exec/yaml_func_terraform_output_test.go
• pkg/auth/providers/mock/identity_test.go
• pkg/auth/identities/aws/assume_role_test.go
• pkg/auth/providers/aws/sso_test.go
• pkg/xdg/xdg_test.go
• pkg/auth/identities/aws/user_test.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/auth/credentials/store_test.go
• cmd/auth_console_test.go
• pkg/auth/identities/aws/permission_set_test.go
• internal/exec/yaml_func_terraform_output_authcontext_test.go
• pkg/auth/providers/aws/saml_test.go
• pkg/auth/cloud/aws/setup_test.go
• pkg/auth/hooks_test.go
• pkg/auth/credentials/keyring_file_test.go
• pkg/auth/cloud/aws/files_test.go
• pkg/auth/manager_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

cmd/**/*.go: Use Cobra's recommended command structure with a root command and subcommands
Implement each CLI command in a separate file under cmd/
Use Viper for managing configuration, environment variables, and flags in the CLI
Keep separation of concerns between CLI interface (cmd) and business logic
Use kebab-case for command-line flags
Provide comprehensive help text for all commands and flags
Include examples in Cobra command help
Use Viper for configuration management; support files, env vars, and flags with precedence flags > env > config > defaults
Follow single responsibility; separate command interface from business logic
Provide meaningful user feedback and include progress indicators for long-running operations
Provide clear error messages to users and troubleshooting hints where appropriate

cmd/**/*.go: New CLI commands must use the command registry pattern via CommandProvider and register through the command registry (see cmd/internal/registry.go).
Commands should embed *_usage.md via //go:embed and render with utils.PrintfMarkdown().
UI (prompts/status) must write to stderr; data outputs to stdout; logging only for system events (never for UI).
For non-standard execution paths, capture telemetry with telemetry.CaptureCmd(); normal paths are auto-enabled via RootCmd.ExecuteC(). Never capture user data.

Files:

• cmd/auth_console_test.go
• cmd/auth_whoami.go
• cmd/auth_env.go

📄 CodeRabbit inference engine (CLAUDE.md)

Use cmd.NewTestKit(t) for any tests that touch RootCmd to auto-clean RootCmd state.

Files:

• cmd/auth_console_test.go

📄 CodeRabbit inference engine (CLAUDE.md)

Use theme colors from pkg/ui/theme/colors.go for UI elements.

Files:

• cmd/auth_console_test.go
• cmd/auth_whoami.go
• cmd/auth_env.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Update README.md when adding new commands and features

Files:

• README.md

📄 CodeRabbit inference engine (CLAUDE.md)

PRs labeled minor or major must include a blog post with filename date prefix and feature name; include and proper tags.

Files:

• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• website/blog/2025-10-21-auth-context-implementation.md

📄 CodeRabbit inference engine (CLAUDE.md)

All PRDs must be placed under docs/prd/ with kebab-case filenames.

Files:

• docs/prd/xdg-base-directory-specification.md

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: XDG Base Directory Specification compliance implementation for atmos toolchain is complete: created toolchain/xdg_cache.go with GetXDGCacheDir() and GetXDGTempCacheDir() functions, updated toolchain/installer.go and cmd/toolchain_clean.go to use these XDG helpers, and changed all cache paths from hardcoded ~/.cache/tools-cache to XDG-compliant ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain fallback).

Applied to files:

• pkg/xdg/xdg.go
• pkg/xdg/xdg_test.go
• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• docs/prd/xdg-base-directory-specification.md
• website/blog/2025-10-21-auth-context-implementation.md
• pkg/auth/cloud/aws/setup_test.go

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain XDG compliance implementation is complete with GetXDGCacheDir() and GetXDGTempCacheDir() functions in toolchain/xdg_cache.go, updated installer.go and toolchain_clean.go to use these helpers, and changed cache paths from ~/.cache/tools-cache to ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain when XDG_CACHE_HOME is not set).

Applied to files:

• pkg/xdg/xdg.go
• pkg/xdg/xdg_test.go
• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• docs/prd/xdg-base-directory-specification.md
• website/blog/2025-10-21-auth-context-implementation.md
• pkg/auth/cloud/aws/setup_test.go

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain has been updated to follow XDG Base Directory Specification with helper functions GetXDGCacheDir() and GetXDGTempCacheDir() in toolchain/xdg_cache.go, using XDG_CACHE_HOME when set and falling back to ~/.cache/atmos-toolchain, making it consistent with atmos core's XDG compliance.

Applied to files:

• pkg/xdg/xdg.go
• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• docs/prd/xdg-base-directory-specification.md
• website/blog/2025-10-21-auth-context-implementation.md
• pkg/auth/cloud/aws/setup_test.go
• website/docs/cli/commands/auth/tutorials/configuring-geodesic.mdx

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: Final XDG Base Directory Specification implementation for atmos toolchain is complete and verified: toolchain/xdg_cache.go provides GetXDGCacheDir() and GetXDGTempCacheDir() functions, all hardcoded ~/.cache/tools-cache paths have been replaced with XDG-compliant paths using ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain fallback), and tests have been updated to expect the new path structure.

Applied to files:

• pkg/xdg/xdg.go
• pkg/xdg/xdg_test.go
• website/blog/2025-10-24-macos-xdg-cli-conventions.md
• docs/prd/xdg-base-directory-specification.md
• website/blog/2025-10-21-auth-context-implementation.md
• pkg/auth/cloud/aws/setup_test.go

Learnt from: Listener430
PR: cloudposse/atmos#844
File: pkg/config/cache.go:17-31
Timestamp: 2024-12-13T15:33:34.159Z
Learning: In `pkg/config/cache.go`, when `XDG_CACHE_HOME` is not set, falling back to `.` (current directory) is acceptable and aligns with the requirement to primarily use `XDG_CACHE_HOME` for the cache directory.

Applied to files:

• pkg/xdg/xdg.go
• docs/prd/xdg-base-directory-specification.md

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: pkg/auth/providers/github/oidc.go:96-100
Timestamp: 2025-09-10T17:34:52.568Z
Learning: The ATMOS_ environment variable binding guideline applies to Atmos configuration variables, not external service-required environment variables like GitHub Actions OIDC variables (GITHUB_ACTIONS, ACTIONS_ID_TOKEN_*) which must use their standard names.

Applied to files:

• website/docs/cli/commands/auth/auth-shell.mdx

Learnt from: aknysh
PR: cloudposse/atmos#863
File: internal/exec/yaml_func_terraform_output.go:34-38
Timestamp: 2024-12-17T07:08:41.288Z
Learning: In the `processTagTerraformOutput` function within `internal/exec/yaml_func_terraform_output.go`, parameters are separated by spaces and do not contain spaces. Therefore, using `strings.Fields()` for parsing is acceptable, and there's no need to handle parameters with spaces.

Applied to files:

• internal/exec/yaml_func_terraform_output_test.go
• internal/exec/yaml_func_utils.go

Learnt from: aknysh
PR: cloudposse/atmos#810
File: internal/exec/yaml_func_terraform_output.go:35-40
Timestamp: 2024-11-30T22:07:08.610Z
Learning: In the Go function `processTagTerraformOutput` in `internal/exec/yaml_func_terraform_output.go`, parameters cannot contain spaces. The code splits the input by spaces, and if the parameters contain spaces, `len(parts) != 3` will fail and show an error to the user.

Applied to files:

• internal/exec/yaml_func_terraform_output_test.go

Learnt from: samtholiya
PR: cloudposse/atmos#1255
File: cmd/describe_affected_test.go:15-15
Timestamp: 2025-05-23T19:51:47.091Z
Learning: The atmos codebase has a custom extension to *testing.T that provides a Chdir method, allowing test functions to call t.Chdir() to change working directories during tests. This is used consistently across test files in the codebase.

Applied to files:

• pkg/xdg/xdg_test.go

Learnt from: samtholiya
PR: cloudposse/atmos#1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.

Applied to files:

• website/docs/cli/commands/auth/usage.mdx

Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-24T14:51:19.340Z
Learning: Applies to **/*.go : Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.

Applied to files:

• pkg/auth/cloud/aws/env.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1452
File: internal/auth/types/whoami.go:14-15
Timestamp: 2025-09-09T02:14:36.708Z
Learning: The WhoamiInfo struct in internal/auth/types/whoami.go requires the Credentials field to be JSON-serializable for keystore unmarshaling operations, despite security concerns about credential exposure.

Applied to files:

• cmd/auth_whoami.go

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain should follow XDG Base Directory Specification like the rest of atmos core, using XDG_CACHE_HOME environment variable when available and falling back to ~/.cache when not set, instead of hardcoding ~/.cache/tools-cache paths.

Applied to files:

• docs/prd/xdg-base-directory-specification.md

Learnt from: Listener430
PR: cloudposse/atmos#844
File: cmd/helmfile.go:37-37
Timestamp: 2024-12-11T18:40:12.808Z
Learning: In the atmos project, `cliConfig` is initialized within the `cmd` package in `root.go` and can be used in other command files.

Applied to files:

• docs/prd/xdg-base-directory-specification.md

Learnt from: aknysh
PR: cloudposse/atmos#775
File: internal/exec/template_funcs_component.go:157-159
Timestamp: 2024-11-12T03:16:02.910Z
Learning: In the Go code for `componentFunc` in `internal/exec/template_funcs_component.go`, the function `cleanTerraformWorkspace` does not return errors, and it's acceptable if the file does not exist. Therefore, error handling for `cleanTerraformWorkspace` is not needed.

Applied to files:

• internal/exec/template_funcs_component.go

Learnt from: samtholiya
PR: cloudposse/atmos#1466
File: toolchain/list.go:39-42
Timestamp: 2025-09-13T18:06:07.674Z
Learning: In the cloudposse/atmos repository, for UI messages in the toolchain package, use utils.PrintfMessageToTUI instead of log.Error or fmt.Fprintln(os.Stderr, ...). Import pkg/utils with alias "u" to follow the established pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: aknysh
PR: cloudposse/atmos#1352
File: pkg/store/artifactory_store_test.go:108-113
Timestamp: 2025-08-15T14:43:41.030Z
Learning: In test files for the atmos project, it's acceptable to ignore errors from os.Setenv/Unsetenv operations during test environment setup and teardown, as these are controlled test scenarios.

Applied to files:

• pkg/auth/cloud/aws/setup_test.go

pkg/perf/perf.go (1)

• Track (121-138)

pkg/auth/cloud/aws/files.go (1)

• NewAWSFileManager (56-83)

pkg/auth/types/interfaces.go (1)

• ICredentials (187-198)

pkg/auth/types/interfaces.go (1)

• ICredentials (187-198)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/auth/providers/mock/identity.go (2)

• Identity (14-17)
• NewIdentity (20-27)

pkg/auth/types/interfaces.go (1)

• Identity (54-89)

pkg/schema/schema_auth.go (1)

• Identity (45-53)

pkg/auth/providers/mock/credentials.go (1)

• Credentials (11-17)

pkg/auth/identities/aws/assume_role.go (1)

• NewAssumeRoleIdentity (111-126)

pkg/auth/types/interfaces.go (2)

• Identity (54-89)
• Provider (13-42)

pkg/schema/schema_auth.go (3)

• Identity (45-53)
• IdentityVia (56-59)
• Provider (18-32)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/types/interfaces.go (1)

• ValidationInfo (201-216)

pkg/xdg/xdg.go (1)

• GetXDGConfigDir (46-48)

pkg/auth/types/interfaces.go (2)

• ICredentials (187-198)
• Identity (54-89)

pkg/auth/identities/aws/user.go (1)

• NewUserIdentity (39-51)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/schema/schema.go (1)

• AuthContext (498-506)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/config/const.go (1)

• EnvSectionName (61-61)

pkg/logger/log.go (1)

• Debug (24-26)

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

pkg/logger/log.go (2)

• Debug (24-26)
• Errorf (59-61)

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

pkg/auth/types/interfaces.go (1)

• ValidationInfo (201-216)

errors/error_funcs.go (1)

• CheckErrorPrintAndExit (58-81)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/auth/providers/mock/credentials.go (1)

• Credentials (11-17)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/auth/types/interfaces.go (2)

• Identity (54-89)
• ValidationInfo (201-216)

pkg/auth/types/interfaces.go (2)

• Identity (54-89)
• ICredentials (187-198)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/auth/providers/mock/credentials.go (1)

• Credentials (11-17)

pkg/auth/identities/aws/permission_set.go (1)

• NewPermissionSetIdentity (36-45)

pkg/auth/types/interfaces.go (2)

• Identity (54-89)
• Provider (13-42)

pkg/schema/schema_auth.go (3)

• Identity (45-53)
• IdentityVia (56-59)
• Provider (18-32)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/types/interfaces.go (1)

• ValidationInfo (201-216)

pkg/schema/schema.go (2)

• AtmosConfiguration (27-65)
• AuthContext (498-506)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/auth/credentials/keyring_file.go (1)

• ErrCredentialsNotFound (36-36)

errors/errors.go (3)

• ErrNoCredentialsFound (386-386)
• ErrIdentityNotFound (393-393)
• ErrInvalidAuthConfig (370-370)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/auth/types/interfaces.go (2)

• Provider (13-42)
• Identity (54-89)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/xdg/xdg.go (1)

• GetXDGConfigDir (46-48)

pkg/logger/log.go (3)

• Errorf (59-61)
• Warn (44-46)
• Debug (24-26)

pkg/config/homedir/homedir.go (1)

• Dir (36-63)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

internal/exec/mock_terraform_output_getter.go (1)

• NewMockTerraformOutputGetter (32-36)

pkg/schema/schema.go (5)

• AuthContext (498-506)
• AWSAuthContext (510-525)
• ConfigAndStacksInfo (527-610)
• AtmosConfiguration (27-65)
• AtmosSectionMapType (14-14)

internal/exec/yaml_func_utils.go (1)

• ProcessCustomYamlTags (13-30)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/logger/log.go (2)

• Errorf (59-61)
• Debug (24-26)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/cloud/aws/setup.go (1)

• SetupFiles (17-45)

pkg/schema/schema.go (2)

• AuthContext (498-506)
• AWSAuthContext (510-525)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/auth/cloud/aws/files.go (1)

• NewAWSFileManager (56-83)

pkg/auth/types/interfaces.go (1)

• ICredentials (187-198)

pkg/auth/types/interfaces.go (1)

• ValidationInfo (201-216)

errors/errors.go (1)

• ErrAuthenticationFailed (375-375)

pkg/schema/schema.go (2)

• AtmosConfiguration (27-65)
• AuthContext (498-506)

pkg/perf/perf.go (1)

• Track (121-138)

internal/exec/terraform_output_utils.go (1)

• GetTerraformOutput (372-448)

pkg/auth/types/interfaces.go (1)

• ValidationInfo (201-216)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/auth/cloud/aws/files.go (1)

• NewAWSFileManager (56-83)

pkg/auth/types/interfaces.go (1)

• ICredentials (187-198)

pkg/schema/schema.go (3)

• AtmosConfiguration (27-65)
• ConfigAndStacksInfo (527-610)
• AuthContext (498-506)

pkg/config/homedir/homedir.go (1)

• Dir (36-63)

pkg/auth/cloud/aws/files.go (1)

• NewAWSFileManager (56-83)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/types/interfaces.go (2)

• ICredentials (187-198)
• ConsoleURLOptions (230-247)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/auth/types/interfaces.go (2)

• ValidationInfo (201-216)
• ICredentials (187-198)

[style] ~52-52: This phrase is redundant (‘OS’ stands for ‘operating system’). Use simply “macOS”.
Context: ..., /Library/Caches` - Provides better macOS system integration - Standard for applications...

(ACRONYM_TAUTOLOGY)

[style] ~61-~61: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...ed If you're upgrading from versions prior to v1.195.0, you're not affected because...

(EN_WORDINESS_PREMIUM_PRIOR_TO)

[style] ~81-~81: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...eps credentials in the old location but affects all Atmos XDG paths (config, cache,...

(EN_REPEATEDWORDS_AFFECT)

[grammar] ~158-~158: Please add a punctuation mark at the end of paragraph.
Context: ...uth/usage) - Updated with correct macOS paths ## Migration Support If you encounter...

(PUNCTUATION_PARAGRAPH_END)

[typographical] ~39-~39: Consider using a typographic opening quote here.
Context: ...| | Testing with hermetic isolation |t.Setenv("XDG_DATA_HOME")|/tmp/test-xyz/data/a...

(EN_QUOTES)

[typographical] ~51-~51: In American English, use a period after an abbreviation.
Context: ... creation for visibility ### CLI Tools vs GUI Applications The XDG Base Director...

(MISSING_PERIOD_AFTER_ABBREVIATION)

[style] ~63-~63: This phrase is redundant (‘OS’ stands for ‘operating system’). Use simply “macOS”.
Context: ...- This provides better integration with macOS system features - Used by native macOS applica...

(ACRONYM_TAUTOLOGY)

[grammar] ~69-~69: Please add a punctuation mark at the end of paragraph.
Context: ...aths for users working across Linux and macOS ## Technical Specification ### Archit...

(PUNCTUATION_PARAGRAPH_END)

[style] ~550-~550: Consider using a different verb to strengthen your wording.
Context: ... compatibility. Rationale: Research showed that CLI tools (gh, git, packer, stripe...

(SHOW_INDICATE)

[style] ~564-~564: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... not be affected** because: 1. Versions prior to v1.195.0 used ~/.aws/atmos/ (legacy p...

(EN_WORDINESS_PREMIUM_PRIOR_TO)

[grammar] ~22-~22: Please add a punctuation mark at the end of paragraph.
Context: ...tion** for consistency with other Atmos data ## Why This Matters **The core proble...

(PUNCTUATION_PARAGRAPH_END)

[grammar] ~52-~52: Please add a punctuation mark at the end of paragraph.
Context: ... this - ❌ AWS_PROFILE - Atmos manages this Key Configuration Details: - **`A...

(PUNCTUATION_PARAGRAPH_END)

69-69: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Define interfaces for major functionality and use dependency injection to enable testability.
Generate mocks using go.uber.org/mock/mockgen via //go:generate directives (never manual mocks).
Prefer functional Options pattern instead of functions with many parameters for configuration.
Use context.Context only for cancellation, deadlines/timeouts, and request-scoped values; never for configuration or dependencies; context should be the first parameter.
All comments must end with periods (godot linter).
Preserve helpful existing comments; update them to match code when refactoring; only remove when incorrect, redundant, or code removed.
Organize imports in three groups (stdlib, third-party, Atmos) separated by blank lines and sorted alphabetically; maintain aliases cfg, log, u, errUtils.
Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.
Use static errors from errors/errors.go; wrap with fmt.Errorf("%w") for chaining; use errors.Join for independent errors; avoid dynamic errors and string comparison; use errors.Is for checks.
Never use //revive:disable:file-length-limit to bypass file size limits; keep files small and focused (<600 lines).
Environment variables must be bound with viper.BindEnv using ATMOS_ prefix (e.g., viper.BindEnv("ATMOS_VAR", "ATMOS_VAR", "FALLBACK")).
Ensure cross-platform compatibility: use filepath.Join instead of hardcoded path separators and prefer SDKs over shelling out to binaries.

Files:

• errors/errors.go
• pkg/hooks/store_cmd.go
• pkg/hooks/store_cmd_nil_handling_test.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/hooks/store_cmd_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• errors/errors.go
• pkg/hooks/store_cmd.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/hooks/store_cmd.go
• pkg/hooks/store_cmd_nil_handling_test.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/hooks/store_cmd_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases

Files:

• website/blog/2025-10-24-macos-xdg-cli-conventions.md

📄 CodeRabbit inference engine (CLAUDE.md)

PRs labeled minor or major must include a blog post with filename date prefix and feature name; include and proper tags.

Files:

• website/blog/2025-10-24-macos-xdg-cli-conventions.md

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests
Test both happy paths and error conditions
Use table-driven tests for multiple scenarios

**/*_test.go: Prefer unit tests with mocks over integration tests; use interfaces + DI; table-driven tests for coverage; target >80% coverage.
Tests must exercise production code paths; avoid duplicating implementation logic in tests.
Use t.Skipf("reason") with clear context when skipping tests; CLI tests may auto-build temp binaries.

Files:

• pkg/hooks/store_cmd_nil_handling_test.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/hooks/store_cmd_test.go

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain has been updated to follow XDG Base Directory Specification with helper functions GetXDGCacheDir() and GetXDGTempCacheDir() in toolchain/xdg_cache.go, using XDG_CACHE_HOME when set and falling back to ~/.cache/atmos-toolchain, making it consistent with atmos core's XDG compliance.

Applied to files:

• website/blog/2025-10-24-macos-xdg-cli-conventions.md

pkg/schema/schema.go (1)

• AuthContext (498-506)

pkg/schema/schema.go (2)

• AtmosConfiguration (27-65)
• AuthContext (498-506)

pkg/schema/schema.go (2)

• AtmosConfiguration (27-65)
• AuthContext (498-506)

[style] ~52-52: This phrase is redundant (‘OS’ stands for ‘operating system’). Use simply “macOS”.
Context: ..., /Library/Caches` - Provides better macOS system integration - Standard for applications...

(ACRONYM_TAUTOLOGY)

[style] ~61-~61: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...ed If you're upgrading from versions prior to v1.195.0, you're not affected because...

(EN_WORDINESS_PREMIUM_PRIOR_TO)

[style] ~81-~81: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...eps credentials in the old location but affects all Atmos XDG paths (config, cache,...

(EN_REPEATEDWORDS_AFFECT)

[grammar] ~157-~157: Please add a punctuation mark at the end of paragraph.
Context: ...uth/usage) - Updated with correct macOS paths ## Migration Support If you encounter...

(PUNCTUATION_PARAGRAPH_END)

69-69: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

75-75: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

83-83: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

128-128: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

173-173: Bare URL used

(MD034, no-bare-urls)

174-174: Bare URL used

(MD034, no-bare-urls)

175-175: Bare URL used

(MD034, no-bare-urls)

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Define interfaces for major functionality and use dependency injection to enable testability.
Generate mocks using go.uber.org/mock/mockgen via //go:generate directives (never manual mocks).
Prefer functional Options pattern instead of functions with many parameters for configuration.
Use context.Context only for cancellation, deadlines/timeouts, and request-scoped values; never for configuration or dependencies; context should be the first parameter.
All comments must end with periods (godot linter).
Preserve helpful existing comments; update them to match code when refactoring; only remove when incorrect, redundant, or code removed.
Organize imports in three groups (stdlib, third-party, Atmos) separated by blank lines and sorted alphabetically; maintain aliases cfg, log, u, errUtils.
Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.
Use static errors from errors/errors.go; wrap with fmt.Errorf("%w") for chaining; use errors.Join for independent errors; avoid dynamic errors and string comparison; use errors.Is for checks.
Never use //revive:disable:file-length-limit to bypass file size limits; keep files small and focused (<600 lines).
Environment variables must be bound with viper.BindEnv using ATMOS_ prefix (e.g., viper.BindEnv("ATMOS_VAR", "ATMOS_VAR", "FALLBACK")).
Ensure cross-platform compatibility: use filepath.Join instead of hardcoded path separators and prefer SDKs over shelling out to binaries.

Files:

• internal/aws_utils/aws_utils.go
• pkg/auth/cloud/aws/env.go
• internal/exec/terraform_output_utils.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• internal/aws_utils/aws_utils.go
• pkg/auth/cloud/aws/env.go
• internal/exec/terraform_output_utils.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/auth/cloud/aws/env.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases

Files:

• website/blog/2025-10-21-auth-context-implementation.md

📄 CodeRabbit inference engine (CLAUDE.md)

PRs labeled minor or major must include a blog post with filename date prefix and feature name; include and proper tags.

Files:

• website/blog/2025-10-21-auth-context-implementation.md

Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-24T14:51:19.340Z
Learning: Applies to **/*.go : Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.

Applied to files:

• pkg/auth/cloud/aws/env.go

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain has been updated to follow XDG Base Directory Specification with helper functions GetXDGCacheDir() and GetXDGTempCacheDir() in toolchain/xdg_cache.go, using XDG_CACHE_HOME when set and falling back to ~/.cache/atmos-toolchain, making it consistent with atmos core's XDG compliance.

Applied to files:

• website/blog/2025-10-21-auth-context-implementation.md

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: XDG Base Directory Specification compliance implementation for atmos toolchain is complete: created toolchain/xdg_cache.go with GetXDGCacheDir() and GetXDGTempCacheDir() functions, updated toolchain/installer.go and cmd/toolchain_clean.go to use these XDG helpers, and changed all cache paths from hardcoded ~/.cache/tools-cache to XDG-compliant ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain fallback).

Applied to files:

• website/blog/2025-10-21-auth-context-implementation.md

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: Final XDG Base Directory Specification implementation for atmos toolchain is complete and verified: toolchain/xdg_cache.go provides GetXDGCacheDir() and GetXDGTempCacheDir() functions, all hardcoded ~/.cache/tools-cache paths have been replaced with XDG-compliant paths using ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain fallback), and tests have been updated to expect the new path structure.

Applied to files:

• website/blog/2025-10-21-auth-context-implementation.md

Learnt from: osterman
PR: cloudposse/atmos#1466
File: website/docs/cli/commands/toolchain/usage.mdx:117-121
Timestamp: 2025-09-08T01:25:44.958Z
Learning: The atmos toolchain XDG compliance implementation is complete with GetXDGCacheDir() and GetXDGTempCacheDir() functions in toolchain/xdg_cache.go, updated installer.go and toolchain_clean.go to use these helpers, and changed cache paths from ~/.cache/tools-cache to ${XDG_CACHE_HOME}/atmos-toolchain (or ~/.cache/atmos-toolchain when XDG_CACHE_HOME is not set).

Applied to files:

• website/blog/2025-10-21-auth-context-implementation.md

pkg/logger/log.go (1)

• Debug (24-26)

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

pkg/schema/schema.go (1)

• Context (409-424)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/logger/log.go (2)

• Debug (24-26)
• Errorf (59-61)

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

pkg/schema/schema.go (1)

• AuthContext (498-506)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/config/const.go (1)

• EnvSectionName (61-61)

[failure] 144-144:
undefined: perf

[grammar] ~22-~22: Please add a punctuation mark at the end of paragraph.
Context: ...tion** for consistency with other Atmos data ## Why This Matters **The core proble...

(PUNCTUATION_PARAGRAPH_END)

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/auth/credentials/keyring_system.go
• pkg/auth/credentials/keyring_file.go
• pkg/auth/manager_logout.go
• pkg/auth/types/interfaces.go
• pkg/auth/manager_whoami.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/credentials/keyring_memory.go
• pkg/auth/types/whoami_test.go
• pkg/auth/manager.go
• pkg/auth/cloud/aws/files.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/credentials/keyring_noop.go
• pkg/auth/cloud/aws/env.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Define interfaces for major functionality and use dependency injection to enable testability.
Generate mocks using go.uber.org/mock/mockgen via //go:generate directives (never manual mocks).
Prefer functional Options pattern instead of functions with many parameters for configuration.
Use context.Context only for cancellation, deadlines/timeouts, and request-scoped values; never for configuration or dependencies; context should be the first parameter.
All comments must end with periods (godot linter).
Preserve helpful existing comments; update them to match code when refactoring; only remove when incorrect, redundant, or code removed.
Organize imports in three groups (stdlib, third-party, Atmos) separated by blank lines and sorted alphabetically; maintain aliases cfg, log, u, errUtils.
Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.
Use static errors from errors/errors.go; wrap with fmt.Errorf("%w") for chaining; use errors.Join for independent errors; avoid dynamic errors and string comparison; use errors.Is for checks.
Never use //revive:disable:file-length-limit to bypass file size limits; keep files small and focused (<600 lines).
Environment variables must be bound with viper.BindEnv using ATMOS_ prefix (e.g., viper.BindEnv("ATMOS_VAR", "ATMOS_VAR", "FALLBACK")).
Ensure cross-platform compatibility: use filepath.Join instead of hardcoded path separators and prefer SDKs over shelling out to binaries.

Files:

• pkg/auth/credentials/keyring_system.go
• pkg/auth/credentials/keyring_file.go
• pkg/auth/manager_logout.go
• pkg/auth/types/interfaces.go
• cmd/auth_whoami.go
• pkg/auth/manager_whoami.go
• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/credentials/keyring_memory.go
• pkg/auth/types/whoami_test.go
• pkg/auth/manager.go
• errors/errors.go
• pkg/auth/cloud/aws/files.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/credentials/keyring_noop.go
• pkg/auth/cloud/aws/env.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• pkg/auth/credentials/keyring_system.go
• pkg/auth/credentials/keyring_file.go
• pkg/auth/manager_logout.go
• pkg/auth/types/interfaces.go
• cmd/auth_whoami.go
• pkg/auth/manager_whoami.go
• pkg/auth/identities/aws/credentials_loader.go
• pkg/auth/credentials/keyring_memory.go
• pkg/auth/manager.go
• errors/errors.go
• pkg/auth/cloud/aws/files.go
• pkg/auth/types/mock_interfaces.go
• pkg/auth/credentials/keyring_noop.go
• pkg/auth/cloud/aws/env.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

cmd/**/*.go: Use Cobra's recommended command structure with a root command and subcommands
Implement each CLI command in a separate file under cmd/
Use Viper for managing configuration, environment variables, and flags in the CLI
Keep separation of concerns between CLI interface (cmd) and business logic
Use kebab-case for command-line flags
Provide comprehensive help text for all commands and flags
Include examples in Cobra command help
Use Viper for configuration management; support files, env vars, and flags with precedence flags > env > config > defaults
Follow single responsibility; separate command interface from business logic
Provide meaningful user feedback and include progress indicators for long-running operations
Provide clear error messages to users and troubleshooting hints where appropriate

cmd/**/*.go: New CLI commands must use the command registry pattern via CommandProvider and register through the command registry (see cmd/internal/registry.go).
Commands should embed *_usage.md via //go:embed and render with utils.PrintfMarkdown().
UI (prompts/status) must write to stderr; data outputs to stdout; logging only for system events (never for UI).
For non-standard execution paths, capture telemetry with telemetry.CaptureCmd(); normal paths are auto-enabled via RootCmd.ExecuteC(). Never capture user data.

Files:

• cmd/auth_whoami.go

📄 CodeRabbit inference engine (CLAUDE.md)

Use theme colors from pkg/ui/theme/colors.go for UI elements.

Files:

• cmd/auth_whoami.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests
Test both happy paths and error conditions
Use table-driven tests for multiple scenarios

**/*_test.go: Prefer unit tests with mocks over integration tests; use interfaces + DI; table-driven tests for coverage; target >80% coverage.
Tests must exercise production code paths; avoid duplicating implementation logic in tests.
Use t.Skipf("reason") with clear context when skipping tests; CLI tests may auto-build temp binaries.

Files:

• pkg/auth/identities/aws/credentials_loader_test.go
• pkg/auth/types/whoami_test.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1452
File: internal/auth/types/whoami.go:14-15
Timestamp: 2025-09-09T02:14:36.708Z
Learning: The WhoamiInfo struct in internal/auth/types/whoami.go requires the Credentials field to be JSON-serializable for keystore unmarshaling operations, despite security concerns about credential exposure.

Applied to files:

• cmd/auth_whoami.go

Learnt from: osterman
PR: cloudposse/atmos#1695
File: pkg/auth/manager.go:169-171
Timestamp: 2025-10-22T14:55:44.014Z
Learning: Go 1.20+ supports multiple %w verbs in fmt.Errorf, which returns an error implementing Unwrap() []error. This is valid and does not panic. Atmos uses Go 1.24.8 and configures errorlint with errorf-multi: true to validate this pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: pkg/auth/identities/aws/user.go:141-145
Timestamp: 2025-09-10T22:38:42.212Z
Learning: The user confirmed that the errors package has an error string wrapping format, contradicting the previous learning about ErrWrappingFormat being invalid. The current usage of fmt.Errorf(errUtils.ErrWrappingFormat, errUtils.ErrAuthAwsFileManagerFailed, err) appears to be the correct pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: pkg/auth/identities/aws/user.go:141-145
Timestamp: 2025-09-10T22:38:42.212Z
Learning: ErrWrappingFormat is correctly defined as "%w: %w" in the errors package and is used throughout the codebase to wrap two error types together. The usage fmt.Errorf(errUtils.ErrWrappingFormat, errUtils.ErrAuthAwsFileManagerFailed, err) is the correct pattern when both arguments are error types.

Applied to files:

• pkg/auth/manager.go

Learnt from: samtholiya
PR: cloudposse/atmos#1466
File: toolchain/list.go:39-42
Timestamp: 2025-09-13T18:06:07.674Z
Learning: In the cloudposse/atmos repository, for UI messages in the toolchain package, use utils.PrintfMessageToTUI instead of log.Error or fmt.Fprintln(os.Stderr, ...). Import pkg/utils with alias "u" to follow the established pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: CR
PR: cloudposse/atmos#0
File: CLAUDE.md:0-0
Timestamp: 2025-10-24T14:51:19.340Z
Learning: Applies to **/*.go : Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.

Applied to files:

• pkg/auth/cloud/aws/env.go

Learnt from: osterman
PR: cloudposse/atmos#1433
File: cmd/theme_list.go:33-36
Timestamp: 2025-08-29T20:57:35.423Z
Learning: In the Atmos codebase, avoid using viper.SetEnvPrefix("ATMOS") with viper.AutomaticEnv() because canonical environment variable names are not exclusive to Atmos and could cause conflicts. Instead, use selective environment variable binding through the setEnv function in pkg/config/load.go with bindEnv(v, "config.key", "ENV_VAR_NAME") for specific environment variables.

Applied to files:

• pkg/auth/cloud/aws/env.go

pkg/auth/types/interfaces.go (1)

• CredentialStoreTypeSystemKeyring (14-14)

pkg/auth/types/interfaces.go (1)

• CredentialStoreTypeFile (17-17)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/logger/log.go (3)

• Errorf (59-61)
• Debug (24-26)
• Info (34-36)

errors/errors.go (8)

• ErrIdentityNotInConfig (428-428)
• ErrKeyringDeletion (425-425)
• ErrLogoutNotSupported (423-423)
• ErrProviderLogout (426-426)
• ErrIdentityLogout (427-427)
• ErrPartialLogout (422-422)
• ErrLogoutFailed (421-421)
• ErrProviderNotInConfig (429-429)

pkg/auth/types/interfaces.go (2)

• Provider (21-50)
• Identity (62-97)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/auth/types/interfaces.go (2)

• Identity (62-97)
• ValidationInfo (212-227)

pkg/ui/theme/colors.go (1)

• ColorRed (16-16)

pkg/auth/types/interfaces.go (3)

• ICredentials (198-209)
• Provider (21-50)
• Identity (62-97)

pkg/auth/types/whoami.go (1)

• WhoamiInfo (6-22)

pkg/logger/log.go (1)

• Debug (24-26)

errors/errors.go (1)

• ErrAwsMissingEnvVars (382-382)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/logger/log.go (1)

• Debug (24-26)

errors/errors.go (1)

• ErrAwsMissingEnvVars (382-382)

pkg/auth/types/interfaces.go (1)

• CredentialStoreTypeMemory (16-16)

pkg/logger/log.go (2)

• Errorf (59-61)
• Debug (24-26)

errors/errors.go (6)

• ErrIdentityNotFound (395-395)
• ErrNoCredentialsFound (388-388)
• ErrExpiredCredentials (389-389)
• ErrMultipleDefaultIdentities (399-399)
• ErrUserAborted (384-384)
• ErrInvalidAuthConfig (370-370)

pkg/auth/credentials/keyring_file.go (1)

• ErrCredentialsNotFound (36-36)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/xdg/xdg.go (1)

• GetXDGConfigDir (46-48)

pkg/logger/log.go (3)

• Errorf (59-61)
• Warn (44-46)
• Debug (24-26)

pkg/config/homedir/homedir.go (1)

• Dir (36-63)

pkg/auth/types/aws_credentials.go (1)

• AWSCredentials (16-23)

pkg/auth/types/interfaces.go (3)

• ICredentials (198-209)
• ValidationInfo (212-227)
• ConsoleURLOptions (241-258)

pkg/auth/types/interfaces.go (2)

• ICredentials (198-209)
• CredentialStoreTypeNoop (15-15)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/logger/log.go (1)

• Debug (24-26)

pkg/perf/perf.go (1)

• Track (121-138)

pkg/logger/log.go (2)

• Debug (24-26)
• Errorf (59-61)

errors/errors.go (1)

• ErrLoadAwsConfig (74-74)

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

cmd/**/*.go: Use Cobra's recommended command structure with a root command and subcommands
Implement each CLI command in a separate file under cmd/
Use Viper for managing configuration, environment variables, and flags in the CLI
Keep separation of concerns between CLI interface (cmd) and business logic
Use kebab-case for command-line flags
Provide comprehensive help text for all commands and flags
Include examples in Cobra command help
Use Viper for configuration management; support files, env vars, and flags with precedence flags > env > config > defaults
Follow single responsibility; separate command interface from business logic
Provide meaningful user feedback and include progress indicators for long-running operations
Provide clear error messages to users and troubleshooting hints where appropriate

cmd/**/*.go: New CLI commands must use the command registry pattern via CommandProvider and register through the command registry (see cmd/internal/registry.go).
Commands should embed *_usage.md via //go:embed and render with utils.PrintfMarkdown().
UI (prompts/status) must write to stderr; data outputs to stdout; logging only for system events (never for UI).
For non-standard execution paths, capture telemetry with telemetry.CaptureCmd(); normal paths are auto-enabled via RootCmd.ExecuteC(). Never capture user data.

Files:

• cmd/auth_logout.go
• cmd/auth_logout_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*.go: All code must pass golangci-lint checks
Follow Go error handling idioms and use meaningful error messages
Wrap errors with context using fmt.Errorf("context: %w", err)
Consider custom error types for domain-specific errors
Follow standard Go coding style; run gofmt and goimports
Use snake_case for environment variables
Document complex logic with inline comments

**/*.go: Define interfaces for major functionality and use dependency injection to enable testability.
Generate mocks using go.uber.org/mock/mockgen via //go:generate directives (never manual mocks).
Prefer functional Options pattern instead of functions with many parameters for configuration.
Use context.Context only for cancellation, deadlines/timeouts, and request-scoped values; never for configuration or dependencies; context should be the first parameter.
All comments must end with periods (godot linter).
Preserve helpful existing comments; update them to match code when refactoring; only remove when incorrect, redundant, or code removed.
Organize imports in three groups (stdlib, third-party, Atmos) separated by blank lines and sorted alphabetically; maintain aliases cfg, log, u, errUtils.
Add defer perf.Track(atmosConfig, "pkg.FuncName")() (or nil if no atmosConfig) plus a blank line at the start of all public functions for performance tracking.
Use static errors from errors/errors.go; wrap with fmt.Errorf("%w") for chaining; use errors.Join for independent errors; avoid dynamic errors and string comparison; use errors.Is for checks.
Never use //revive:disable:file-length-limit to bypass file size limits; keep files small and focused (<600 lines).
Environment variables must be bound with viper.BindEnv using ATMOS_ prefix (e.g., viper.BindEnv("ATMOS_VAR", "ATMOS_VAR", "FALLBACK")).
Ensure cross-platform compatibility: use filepath.Join instead of hardcoded path separators and prefer SDKs over shelling out to binaries.

Files:

• cmd/auth_logout.go
• cmd/auth_logout_test.go
• pkg/auth/manager.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Document all exported functions, types, and methods with Go doc comments

Files:

• cmd/auth_logout.go
• pkg/auth/manager.go

📄 CodeRabbit inference engine (CLAUDE.md)

Use theme colors from pkg/ui/theme/colors.go for UI elements.

Files:

• cmd/auth_logout.go
• cmd/auth_logout_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

**/*_test.go: Every new feature must include comprehensive unit tests
Test both happy paths and error conditions
Use table-driven tests for multiple scenarios

**/*_test.go: Prefer unit tests with mocks over integration tests; use interfaces + DI; table-driven tests for coverage; target >80% coverage.
Tests must exercise production code paths; avoid duplicating implementation logic in tests.
Use t.Skipf("reason") with clear context when skipping tests; CLI tests may auto-build temp binaries.

Files:

• cmd/auth_logout_test.go

📄 CodeRabbit inference engine (CLAUDE.md)

Use cmd.NewTestKit(t) for any tests that touch RootCmd to auto-clean RootCmd state.

Files:

• cmd/auth_logout_test.go

📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)

Place business logic in pkg rather than in cmd

Files:

• pkg/auth/manager.go

Learnt from: osterman
PR: cloudposse/atmos#1695
File: pkg/auth/manager.go:169-171
Timestamp: 2025-10-22T14:55:44.014Z
Learning: Go 1.20+ supports multiple %w verbs in fmt.Errorf, which returns an error implementing Unwrap() []error. This is valid and does not panic. Atmos uses Go 1.24.8 and configures errorlint with errorf-multi: true to validate this pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: pkg/auth/identities/aws/user.go:141-145
Timestamp: 2025-09-10T22:38:42.212Z
Learning: The user confirmed that the errors package has an error string wrapping format, contradicting the previous learning about ErrWrappingFormat being invalid. The current usage of fmt.Errorf(errUtils.ErrWrappingFormat, errUtils.ErrAuthAwsFileManagerFailed, err) appears to be the correct pattern.

Applied to files:

• pkg/auth/manager.go

Learnt from: Benbentwo
PR: cloudposse/atmos#1475
File: pkg/auth/identities/aws/user.go:141-145
Timestamp: 2025-09-10T22:38:42.212Z
Learning: ErrWrappingFormat is correctly defined as "%w: %w" in the errors package and is used throughout the codebase to wrap two error types together. The usage fmt.Errorf(errUtils.ErrWrappingFormat, errUtils.ErrAuthAwsFileManagerFailed, err) is the correct pattern when both arguments are error types.

Applied to files:

• pkg/auth/manager.go

Learnt from: samtholiya
PR: cloudposse/atmos#1466
File: toolchain/list.go:39-42
Timestamp: 2025-09-13T18:06:07.674Z
Learning: In the cloudposse/atmos repository, for UI messages in the toolchain package, use utils.PrintfMessageToTUI instead of log.Error or fmt.Fprintln(os.Stderr, ...). Import pkg/utils with alias "u" to follow the established pattern.

Applied to files:

• pkg/auth/manager.go

pkg/utils/markdown_utils.go (1)

• PrintfMarkdownToTUI (89-93)

pkg/utils/log_utils.go (1)

• PrintfMessageToTUI (33-35)

errors/errors.go (1)

• ErrInvalidFlag (108-108)

cmd/testkit_test.go (1)

• NewTestKit (55-65)

errors/errors.go (1)

• ErrInvalidFlag (108-108)

pkg/logger/log.go (2)

• Errorf (59-61)
• Debug (24-26)

errors/errors.go (6)

• ErrIdentityNotFound (395-395)
• ErrNoCredentialsFound (388-388)
• ErrExpiredCredentials (389-389)
• ErrMultipleDefaultIdentities (399-399)
• ErrUserAborted (384-384)
• ErrInvalidAuthConfig (370-370)

pkg/auth/credentials/keyring_file.go (1)

• ErrCredentialsNotFound (36-36)

pkg/auth/types/interfaces.go (1)

• ICredentials (198-209)

pkg/perf/perf.go (1)

• Track (121-138)